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Introducing ProtoGen+. Visual tools with the most awesome 
workbench ever created for Windows development. 


he future has arrived—a complete 
point-and-click, WYSIWYG 
workbench that lets you create 
dazzling applications without 
writing a line of code. 


Discover the ease and 
productivity of visual 
development! 


Paint your 
screens. Design 
a menu and link 


screens togeth¬ 
er. Test the flow 
in a live environ¬ 
ment, and gen¬ 
erate code for 
ANSI C, C++ 
for OWL or MFC 
or Pascal with 
objects. It’s that 
easy. 

And this 

open! ProtoGen+ 
will work with 
your database, 
compiler, 
libraries and extensions. Powerful 


Visually 

develop 

screens 



Create a menu 
and connect 
screens & dialogs 



Test the applica¬ 
tion's screen llow in 
a live environment 



Instantly generate 
source code in 
Pascal, C or C++ 


add-on features, like SQLView offer 




Bring your applications to life using the latest 
visual design tools! 


workbench access to multiple 
databases to develop client/server and 
xBase applications. Snap-in compo¬ 
nents make ProtoGen+ open to future 
development technologies—whatever 
they may be. 

ProtoGen+ is easy to learn, 
speeds your development cycle and 
protects your investment by generat¬ 
ing C.C++ and Pascal. We guarantee 
you'll 
prototype 
and generate 
exciting 
applications 
faster than 


The most powerful, open set of 
Visual Development Tools ever! 
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Point-and-click to paint 
screens with bitmaps, 
icons, tables, data valida¬ 
tion, custom colors, fonts, 
3D effects, visual tool¬ 
bars, status lines, balloon 
help, MD1 and more! 


you ever 

thought 

possible! 
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The Visual Development Edge™ 

All products named are trademarks of their 
respective companies. ©1993 ProtoView Development 


Build win¬ 
dows, forms, 
dialog boxes, 
tool bars 

Output C. 
C++ and 
Pascal with 
Objects 

Create new 
designers! 
Source 
included 


Dialog 

Menu 

Editor 

Designer 

Code 

ProtoView 

Gener¬ 

Screen 

ator 

Manager 

Custom 

Win- 

Visual 

Control 

Designer 

Library 


Quickly 
create a. 
menu using 
templates 

Data valida¬ 
tion, 3-D 
effects, MDI 
and more 

Rich library 
of visual 
control 
objects 



Snap-in 

Code 

Generators 


License our technology to 
create new code generators 


Fasten your seatbelt 
for ProtoGen+l 


Only 


(list price 
$395) 


$199 

1 - 800 - 231-8588 

Ask for Ext. 60 
In NJ, call (908) 329-8588 
ProtoGen+'s SQLView access to multiple 
databases is available at an additional price; 
ask about it when you call. 
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No matter what database they throw at you, 
you’ll connect with Q+E ODBC Pack. 


Fastball, slider, or change-up. 
dBASE, Paradox, or Oracle. If you want 
to connect, you know you’ve got to 
react fast. 

With the comprehensive lineup 
of over 20 drivers in Q+E ODBC Pack, 
you can. 

Cover all your bases with Q+E. 

Drivers are the critical link between 
your ODBC-compliant applications, 
your network, and your databases. And 
because their quality directly affects the 
performance of your applications, it’s 
vital that you have superior drivers. 

Don’t risk costly errors. Rely on 
Q+E Software for fast, dependable 
drivers. 

Q+E ODBC Pack delivers: 

• Comprehensive coverage: Connect all 
ODBC-compliant applications to all 
major SQL and PC DBMS with Q+E 
ODBC Pack. 



• Consistent access: Q+E ODBC Pack 
drivers make all databases look the same 
so you don’t have to change the way you 
work every time you change databases. 

• State-of-the-art technology: Q+E ODBC 
Pack gives you the same database access 
technology used by leading software 
publishers. Plus all drivers are certified 
through Q+E Software’s ODBC Verifi¬ 
cation Suite. 

• High-level implementation: With Q+E 
ODBC Pack you get full SQL, transac¬ 
tion processing, and even network lock¬ 
ing support for non-SQL DBMS. And 
it’s the only set of drivers that sports a 



consistent level of ODBC "" 

Core, Level 1, and selected Level 2 
functions. 

• One-stop, cross-platform support: No 
other set of ODBC drivers offers the 
range of support available from Q+E 
Software. Support is available for 
Windows; support for OS/2, Windows 
NT, Macintosh, and Solaris will be 
available in early 1994. 

Complete, dependable, and quick, 
Q+E ODBC Pack makes sure your applica¬ 
tions perform—no matter what 
database you have to face. 


Q.+-E ODBC Pack provides support for the following databases. 

Oracle, Sybase, Microsoft SQL Server, dBASE, INGRES, Paradox, DB2, SQL/400*, Btrieve, 
DB2/2, INFORMIX, NetWare SQL, Excel .XLS files, text files, PROGRESS, XDB, SQLBase, 
SQL/DS*, Teradata*, HP ALLBASE, and HP IMAGE/SQL; gateways: Micro Decisionware 
and DB2/2-DDCS/2 (‘requires a gateway). 

Q.+E ODBC Pack drivers link all ODBC-compliant applications, 
including the following, to all major SQL and PC databases. 

Excel 5, Access, Visual Basic, PowerBuilder 3, WinWord 6.0, Lotus 1-2-3 Rel. 4, report 
writers, query and reporting tools, and many others. 



Try Q+E ODBC Pack for 
30 days, risk-free ! 

Make sure your ODBC-com¬ 
pliant applications work tomorrow. 
Put Q+E ODBC Pack on your 
team today! Purchase directly from 
Q+E Software. At only $199 , it’s a 
steal! 

If you are not completely sat¬ 
isfied, return it within 30 days for a 
full refund. No hassles. 

No delays. No errors. 

Call 1-800-876-3101 

Ext. DO 19 
8 am to 8 pm EST 


S HH ® Database 

I \ L| Access for 

^ Client Server 

fci Computing™ 

EeSSSSESmbM 


Q.+E Software 

5540 Centerview Drive, Suite 324 * Raleigh, NC 27606 
800-876-3101, (919) 859-2220, Fax (919) 859-9334 


• Q+E Software Europe (31) 1022 02022; Fax (31) 1045 63348 • Q+E Software (Deutschland) GmbH, (49) 228 970760; Fax (49) 228 9707610 • Q+E Software (UK) Ltd., (44) 273 489 888; Fax (44) 273 486 224 
©1993 Q+E Software. Q+E is a registered trademark of Q+E Software. Other brand and product names are the property of their respective owners. 

□ Request 228 on Reader Service Card □ 











Windows/DOS 

□ DEVELOPER'S JOURNAL 



“Ultimate Frisbee" image by Robert Ward. 


C++ 


A Windows NT C++ Class for Asynchronous I/O. 25 

When your DOS program writes to a file, it can’t do anything else until the hard disk 
controller completes the I/O operation. Under Windows NT, though, you can write programs 
that perform useful work while waiting for slow I/O devices to complete operations. This 
article looks at asynchronous I/O under Windows NT and provides a C++ class that can help 
your next program do something productive during file I/O. 

Paula Tomlinson 

C++ Member Function Callbacks. 47 

Callback functions, especially window procedures, are the conduit through which Windows 
event notifications flow. When you switch from C to C++, it is only natural to want to use a 
class member function as a callback function. Unfortunately, that is not trivial, since a class 
member function must be passed an implicit pointer to the object it is associated with. This 
article provides the code you need to use C++ class member functions as callbacks, as 
easily as you used to use C functions for callbacks. 

Craig Arnush 

Seven Borland C++ v4.0 Tips. 81 

Anytime you install a major upgrade to your C++ compiler, you are going to run into a few 
hitches. This article gives you seven tips that can make your life a bit easier as you move up 
to Borland C++ v4.0. 

Ron Burk 


Features 


Automatic Tear-Off Menus: Part 1 . 7 

Pulldown menus offer a compromise between quick access to commands and limited screen 
real estate. User interface environments like Motif give the user more flexibility by offering 
Tear-off menus" — the user can drop a menu and then specify that it stay visible in a top¬ 
most window for further selections. This article gives you the code you need to easily and 
transparently turn the menus in your Windows application into tear-off menus. 

Paul Bonneau 

Windows Multimedia: Part 2 — Spiral Bitmap Special Effects . .41 

Graphics, animation, and sound are creeping into lots of Windows applications. One way to 
ease into multimedia is to display your bitmaps with flair, rather than a single call to BitBItf). 
Charles continues his look at bitmap special effects by showing how to draw bitmaps with a 
spiral effect. 

Charles Mirho 


Columns 

Practical C++: Member Function Pointers. 57 

Taking a break from building the Windows User Interface MANager (WUIMAN), this month’s 
column looks at a problem using pointers to member functions with Microsoft’s C++ 
compilers. 

Ron Burk 
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Advanced. Serious. Technical. 


Windows Questions & Answers. . 63 

Robert Mashlan points out a better way to force Windows to redraw a window after you change 
its style bits. Steve Schachter asks how to safely wait for a particular message to arrive; Paul 
supplies a function called WaitMsgO to handle the nasty cases. Finally, Ivan Figueredo asks 
how to put menu bars on child windows, and Paul replies with a discussion and complete code 
example. 

Paul Bonneau 

Tech Tips: Persistent Windows. 74 

Some applications have a need to remember their window placement across invocations. 

This is one of those user interface touches that can help make your program more appealing 
to users. Jason M. Rinn shows how to do this in C and C++. 

Leor Zolman 
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Instantlnfo. 48 
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You can obtain source code for Windows/DOS Developer's Journal (including unpublished code) 
from: 

CompuServe — GO CLMFORUM, Library 7 (R&D Publications). 

GEnie — in the Windows Roundtable at page 1335 (Keyword:Windows). 

USENET (Archived by UUNET Technologies): uunet !-/pub1 i shed/wi ndowsdos/19YY/monYY .zip 
Accessible via anonymous FTP from ftp.uu.net or via uucp from (900) GOT-SRCS (login name 
“uucp,” no password, $.50 per minute). 

BBSs: 

Phoenix Chapter ACM Library — (602) 970-0474; 

The Programmer’s Corner — 301-596-7692 or (410) 995-6873; 

The Courts of Chaos — (501) 985-0059; 
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Cornerstone — (206) 362-4283; 

The Brass Cannon BBS, Orem, UT. Public access: (801) 226-8310; subscriber access (USR 
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Are you 
avoiding 
version 
control? 

Version control isn't just for teams! 

If you’ve ever accidentally deleted 
source crucial to a project, or 
introduced a bug into working code, 
you know you need a version control 
system. Until now VCS’s have been 
expensive and notoriously difficult to 
maintain. Introducing Source Control: 
finally, individual programmers can 
track incremental code changes, just 
like large companies do for their most 
important projects! 

Think of it as object-oriented 
version control. 

Source Control’s "project orientation” 
will take full advantage of your object- 
oriented code by allowing you to share 
code among active projects. 

Developing for multiple platforms? 
Source Control is available now for DOS, 
Windows, NT, Macintosh, OS/2 and 
UNIX. All of these versions are 
transparent across a network so you 
can work with one integrated code base 
rather than managing time consuming, 
unnecessarily redundant systems. 

If you are part of a team... 

Source Control grows easily to meet the 
needs of team development. A single 
user can get started for less than $300 
(list price) and licenses are available in 
increments of five, ten and more. You 
can economically install Source Control 
on your server and get instant, 
project-wide status reports. Find out 
the who, what, where and when of each 
component as you speed your team to 
that final build deadline. 

Upgrade from PVCS! 

Make a quick transition from your 
current configuration management 
system with Source Control’s PVCS 
conversion utility. Add Powerline’s 
make utility, Source Make, and 
automatically update files without time 
consuming manual check-in/check-out 
procedures. Start on your way to a fully 
integrated configuration management 
system! 

Call for more information! 

Powerline Software is dedicated to 
providing a suite of compiler and 
platform independent developer’s tools, 
including Source Print+, for source code 
management and Source View, the 
run-time debugger for C and C++. 



SOURCE CONTROL 

SOURCE MAKE 

1 - 800 - 257-5773 


SOFTWARE INCORPORATED 


1306 Western Avenue, Suite 203, Seattle, WA 98101 
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From 

the Editor 


Next month is our Windows NT theme issue, and I was noticing that we are one of 
the few programming magazines still featuring hands-on Windows NT programming arti¬ 
cles. I suspect that one reason is that all the press attention that NT received before it 
shipped helped to create an unreasonable expectation of how well it would sell; an 
operating system with the features of NT dearly requires more horsepower than the 
average desktop PC has at this point. Another reason is the ramping up of press cover¬ 
age for Chicago, the version to follow Windows 3.1. We will certainly write about Chi¬ 
cago, as soon as Microsoft lifts the legal restrictions that prevent us from covering it. 
However, we also plan to continue our NT coverage for a total of about six to eight 
articles during 1994. The trade press may think that Windows NT is inert at this point, 
but that is a mistake. 

One place you can see the effect of Windows NT is in CPU prices. Intel plans to start 
aggressively dropping Pentium prices, and one reason is the portability of Windows NT. 
NT already runs on the MIPS and the DEC Alpha, and it should soon be commercially 
available on the Power PC. The portability of NT is going to make CPU manufacturers 
compete directly on price and performance, and the result will be faster, cheaper hard¬ 
ware, and more modestly priced machines that can comfortably run NT. In effect, NT is 
helping produce the lower hardware prices it needs to become a big seller. 

Another place you can see the presence of NT is in multiprocessor machines. The 
February 1994 Computer Shopper reports that you can purchase a dual-processor machine 
(dual 486DX2/66 CPUs, 16Mb of RAM, 527Mb IDE drive, a single 3.5" floppy, CD-ROM 
drive, SVGA adaptor, monitor, and mouse) for only $4,000! The day when I can edit my 
source code on one CPU while a large compilation is running at full speed on a second 
CPU is just $4,000 away now. I predict you will see a lot more multiprocessor machines 
this year, further complicating your next hardware purchase - should you buy a Pentium, 
a RISC-based PC, or a triple-486 multiprocessor machine? 

Speaking of multiprocessing, take a look at the COMMtelligence coprocessor in our 
New Products section this month. If I understood the press release correctly, this board 
doesn't just relieve your main CPU of the task of handling serial port interrupts (at 9600 
baud, that is a serious load, by the way). This board apparently lets you download a . exe 
onto the coprocessor, so you could offload higher-level communications processing, such 
as code that implements ZMODEM or Kermit, onto the coprocessor board. The .exe 
thinks it is running in a DOS environment, so it can go ahead and access interrupts and 
I/O ports just as it did on the main CPU. What a great ideal 

So even though Windows NT won't take over the desktop this year, don't write it off 
just yet. Cheaper hardware and its ability to take advantage of multiprocessing systems 
will help build NTs momentum during the next year. That's why Windows NT is another 
one of the Windows programming topics you can count on us to keep you up-to-date on. □ 


Ron Burk 

Editor 

CIS; 70302,2566 ; Internet: ronb@rdpub.com (“... !uunet!rdpub!ronb") 
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Develop 

Windows Applications 
Quickly and Easily 


Phase3 Has Everything You Need 


Visual Development 

The Phase3 visual development environment 
provides a comprehensive suite of tools for 
screen creation. All standard Windows 
screen objects - push buttons, radio buttons, 
dialog boxes, etc. - are selectable from icon 
bars and are dynamically placed and sized 
on the screen as appropriate for the 
application. Standard Windows APIs are 
available from list boxes and are supported 
with on-line documentation. 


Phase3 Database 

Phase3 includes a relationally complete 
database supplied as a Windows DLL. The 
database supports complex data relation¬ 
ships and access and data manipulation by 
any language through a comprehensive 
suite of supplied database routines. 
Database integrity is enhanced with 
rollback recovery and transaction control. 
The Phase3 data dictionary simplifies data 
model definition and maintenance. 


Query and Reporting 

The Report Writer includes standard 
features like flexible headers, footers, free 
text, calculated fields, sort group sections 
and breaks, and subtotals. Reports can also 
include bitmaps of drawings and photo¬ 
graphic images. Queries are executed with 
the Database Browser which also allows 
data entry and manipulation. Railway 
diagrams assist in query creation, prompt¬ 
ing the user for appropriate selections and 
eliminating syntactical errors. 



Royalty-Free Applications 

Windows is a trademark of Microsoft Corporation. Turbo Pascal 
for Windows and Borland Pascal 7.0 are trademarks of Borland 
International, Inc. All other trademarks or sen/ice marks are 
recognized as the property of their respective owners. 


Lower CASE, E-R Modeling 

Phase3 automates logical data model design 
with Entity-Relationship modeling. After a 
user describes entity relationships graphi¬ 
cally and enters field descriptions, Phase3 
generates the physical database based on an 
analysis of the entity relationships. Phase3 
automatically includes foreign keys in 
appropriate tables and restructures the 
database as requirements change. Phase3 
suggests appropriate referential integrity 
constraints to be enforced at runtime. 


Hierarchy Chart 

Phase3 maintains a graphical map of an entire 
application. The Hierarchy Chart includes all 
windows, dialogs, reports, and code routines. 
To access the underlying C or Pascal source 
code, simply point-and-click on any node. 
Phase3 generated source is easily accessed 
and extended with user written routines. User 
code is preserved even if an application is 
regenerated. The Hierarchy Chart and E-R 
Diagram provide instant core documentation 
for an application. 


Help Generator 

The Phase3 Help Generator allows the easy 
creation of a complete Windows application 
help subsystem including context sensitive 
on-line help. The Help Generator includes its 
own text editor that gives complete control 
over the content, appearance, and branching 
logic through highlighted trigger text. Phase3 
generates a Windows compatible file with an 
“.HLP” extension that is then accessible 
from within the Phase3 created application. 
No other external tools are required. 


"... a thoroughly remarkable product... 
very Impressive” 

Jeff Duntemann 

PC Techniques 

▲ ▲ ▲ 

“I was very impressed with Phase3, and using it 
made me wish I had learned Windows programming 
with a tool like this. Now that I know what it has to 
offer, I’ll probably use it to build the frame for most 
of my programs.” 

L, John Ribar 

Windows Tech Journal 

▲ ▲ A 

“Phase3 hides the complexity of Windows program¬ 
ming but still allows an experienced programmer to 
drill down and extend generated C or Pascal source 
code, providing ultimate control.” 

Randy Goodhew 

Computer Software Columnist 

AAA 

“Phase3 takes an intuitive, innovative approach to 
developing Windows applications. It’s a pleasure to 
work with and has greatly boosted our productivity. 
One of the most important issues for us is that their 
technical support is excellent.” 

Reuben Halevi 

ISoft D&M 

AAA 

“It’s easy to put together an application with Phase3 
- everything’s integrated. And the Phase3 database 
is terrific. It’s closer to true relational than anything 
we’ve found.” 

Michael Erickson 

Prism Business Solutions 
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Order Now 

800 - 851-5650 

Or Call for Free Demo Disk 
Fax (805) 641-9083 


CALL NOW FOR COMPETITIVE UPGRADE PRICING 
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GSS*CGI Graphic 


Soon available on all platforms: 

MS-Windows, Windows NT, OS/2 PM, Solaris, UNIX on PCs and workstations. 
Your application written with the GSS*CGI Graphic Tools 
will be portable to all platforms. 



GSS*GKS 


Ik 


Wi 


Graphics Development Toolkit enables you to develop 
applications in a device and system independent way 
through the help of device-specific drivers based on the 
ISO CGI Standard. GSS*GDT consists of a library with 
more than 160 callable C and FORTRAN functions and is 
compatible with the graphics development tools from IBM 
and SCO. 

GSS*GDT is available for DOS, MS-Windows, Windows 
NT, OS/2 PM, Interactive Unix, Onsite Unix SVR 4.2 and 
Solaris. 

Versions for SCO Unix, UnixWare and HP Workstations will 
be soon available. 


Graphical Kernel System is a C and FORTRAN function 
library that enables you to develop portable graphic 
applications which include e.g. user interaction, coordinate 
transformation and object segmentation, based on the ISO 
GKS Standard. GSS'GKS, which is installed in large 
quantities on the DOS platform and has been proved 
successful for years, is now available for the graphical user 
interfaces and therefore offers the software developer a 
smooth transition to the new windowing systems. 
GSS*GKS is available for DOS, MS-Windows, Windows 
NT, OS/2 PM, Interactive Unix, Onsite Unix SVR 4.2 and 
Solaris. 

Versions for SCO Unix, UnixWare and HP Workstations 
will be soon available. 
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GSS*GCT 


GSS*EVT 

- 





EMATEK Vectorfont Toolkit enables you to integrate 
vectorfonts into your application. Supported font formats 
are PCL5, PostScript Type 1, TrueType and Bitstream 
Speedo. GSS*EVT offers a variety of additional elements 
and attribute functions like character height and gap, 
rotation and italicize angle, fill area pattern and outline- 
width, shadow, background boxes, leader and underlining 
as well as sub- and superscripting for scientific purposes. 
GSS*EVT is an add-on for GSS*GDT, GSS'GKS, 
MS-Windows SDK and will be ported to all popular 
graphical user interfaces. 


Graphics Charts Toolkit provides you with high-level 
functions to integrate presentation graphics into your 
application. With only a few calls you can output pie, bar, 
line, step, schedule or text diagrams on a display or 
printer. Each part of the chart can be altered through the 
related attribute functions. GSS'GCT is an add-on for 
GSS*GDT and GSS’GKS and will be ported to all popular 
graphical user interfaces, thus providing portable presen¬ 
tation graphic capabilities for all supported systems. 
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Automatic Tear-Off Menus 
Part 1 


Paul Bonneau 



Today's different graphical user interfaces have a lot in common - for ex¬ 
ample, all have windows and controls. This shouldn't be surprising since they 
are all derivatives of Xerox Parc's Star. But some GUIs have unique features. In 
particular, tear-off menus are commonplace on UNIX-hosted GUIs, but are not 
supported by Windows. 

Ordinary popup and pulldown menus are an attempt to give you quick ac¬ 
cess to application commands while using a minimum of screen space. If the 
application is designed well, the most common commands will appear on top- 
level menus, requiring only one click to display the menu and one click to 
select the command. However, even in the best designed application, users 
must sometimes access the same menu repeatedly, making the simple action 
of pulling down the menu tedious (especially if the desired menu is a sub-menu 
or sub-sub-menu). 

Tear-off menus give the user the ability to pull down a menu and then 'pin' 
it, so that it stays visible on the screen for quick access to its commands. In 
fact, Motif even uses a small pushpin icon to show that a menu has been 
'pinned' or 'torn off' in this fashion. The torn-off menu stays on top of your 
application window, remaining visible and accessible until you delete it. This 
article presents a DLL that you can use in your existing Windows applications, 
with only small changes in your code, to provide your users with tear-off 
menus. 

The Big Picture 

I first began thinking about tear-off menus in Windows years ago. And it 
wasn't until just recently, after not thinking about it for a long time, that I 
finally figured out a way to implement them. The big problem is that the Win¬ 
dows menu manager is inextricably woven into USER (the component DLL that 
implements user interface functionality). Windows' menu manager does not 
possess a clean modular interface that you can easily customize. This means 
that you either play by the rules of the menu manager API functions, or you 
write your own menu manager from scratch. But the menu manager is a non¬ 
trivial body of code - it knows how to parse the arcane binary menu resource 

format, provide dynamic hierarchical menus, al¬ 
low variable height and owner-draw menu 
items, and provide the remarkably complex 
mouse and keyboard menu interface. 


eE3= 

Borland C++ v3.1 

1 Symantec C++ v6.0 


Microsoft C/C++ V8.0 


Paul Bonneau was a developer of HyperChem, a molecular modeling system, and 
more recently, of Creative Writer, a word processor for children. He works for Microsoft 
Corporation as a Software Design Engineer. The opinions expressed in this article are 
Paul's alone and not those of Microsoft. 
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VMenu Item 1 
Menu Item 2 
Menu Item 3 
Menu item A 


Figure 1 A tear-off menu 
window 


Early last December I had a con¬ 
versation with Ivan Figueredo (a 
reader who has posed several very 
interesting questions to the Q&A col¬ 
umn), who remarked that being able 
to implement tear-off menus would 
be a very cool thing to do. This got 
me started thinking about them 
again. A week later I was at Mi¬ 
crosoft's Win32 Developer's Confer¬ 
ence in Anaheim. They took us all to 
Disneyland, and I was watching the 
impressive Fantasmic show, when I 
realized that smoke and mirrors can 
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actually be a good thing (okay, so I 
should say back projectors and walls 
of mist). Who cares how the thing is 
implemented as long as the user has 
a positive experience? 

The same philosophy works for 
tear-off menus. The initial problem in 
implementing them is that the Win¬ 
dows API gives you no way to keep 
a menu visible after the user interacts 
with it - menus are essentially modal 
windows that seize the mouse and 
keyboard while they are present. I 
needed an easy way to keep the 
menu visible but still get control back 
from the menu manager. Why not 
just show a window with a picture of 
a menu on it, and if the user clicks it, 
then present the real thing? The Win¬ 
dows API provides a key function, 
TrackPopupMenuO, that lets your pro¬ 
gram make a menu appear exactly 
when and where on the screen you 
want. Even though TrackPopupMenuO is 
a modal function that returns as 
soon as the user makes a menu se¬ 
lection or cancels the menu, it's pos¬ 
sible to drop it right on top of a pic¬ 
ture of the menu so that the user 
only sees a brief flash. 

Flere is my basic strategy, then: to 
tear off the currently displayed menu, 
the user presses the right mouse but¬ 
ton. At that time, I quickly snap the 
screen bits that contain the menu, 
dismiss the menu, copy the menu im¬ 
age into a small, topmost window in 
the same screen position, and then I 
return control to the application, 
leaving a window with a fake menu 
in it visible. If the user tries to click 
on an item in my fake menu, I se¬ 
cretly call TrackPopupMenuO to pop the 
real menu up in exactly the same 
place, so it can process the menu se¬ 
lection and execute the desired com¬ 
mand. This is the tack 1 took, and a 
few days and 707 lines of code later, 
I had a DLL ( tearoff.dll) that lets you 
give your existing application auto¬ 
matic tear-off menus, just by adding 
one or two function calls. 

The Tear-Off User Interface 

I had some preliminary ideas 
about the user interface I was going 
to implement. Basically, I thought 
Windows tear-offs should behave 
similarly to those found in the UNIX 
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GUIs. This is a typical programmer's 
way of looking at things, and after a 
conversation with W/DDJ's editor, 
Ron Burk, I realized it was the wrong 
approach. Ron stressed the point that 
whatever I implemented should have 
some common 'look and feel' that 
users are already accustomed to. The 
large majority of Windows users 
probably don't even know what a 
'UNIX' is! 

It would be much better to exploit 
some similar Windows Ui paradigm 
that users are already familiar with. 
Fortunately, tool bars, which have be¬ 
come so popular lately, are very 
close to tear-off menus. Conceptually, 
a tool bar is just a menu of graphical 
buttons. I looked at both Microsoft 
Excel 4.0a (as I write this I am wait¬ 
ing for Excel 5.0, which has only just 
started shipping, to arrive) and Word 
6.0 as models for tool bar behavior, 
since they are such huge-selling ap¬ 
plications. Interestingly enough, there 
is a fundamental difference in the 
two implementations. 

While both applications allow the 
user to detach a tool bar from the 
main window, Excel's tool bars are 
implemented as child windows, and 
are therefore limited to the bounda¬ 
ries of Excel's main window. Word's 
tool bars are implemented as popup 
windows, so can be placed anywhere 
on the screen. After using both, I 
think Word's approach is the more 
friendly of the two, since the user 
doesn't have to clutter up the main 
window with tool bars. It will be in¬ 
teresting to see if Excel 5.0 re-imple- 
ments its tool bars as popup win¬ 
dows. 

Tool bars display a miniaturized 
version of the standard Windows 
caption at the top of the tool bar 
window, in addition, there is a cus¬ 
tom sizing border that lets you recon¬ 
figure the tool bar into one of several 
preset shapes, a feature that tear-off 
menus do not require. The tool bar 
can be moved by a left mouse dick- 
and-drag operation with the initial 
mouse down occurring on any non¬ 
button area of the tool bar. A stand¬ 
ard-looking ghost frame is moved 
with the mouse during a drag opera¬ 
tion, instead of the entire tool bar 
window. 


When Word is inactive, all tool 
bar captions are drawn using inactive 
colors (caption background and cap¬ 
tion text); when it's active, all are 
drawn using active colors. Clicking on 
any tool bar window when Word is 
not the active application will acti¬ 
vate Word and bring its main win¬ 
dow to the top of the z order. Click¬ 
ing the miniaturized system icon dis¬ 
misses the tool bar; it does not cause 
a system menu to pop up. Actually, 
to be precise, one must both mouse 
down and mouse up over the mini¬ 


aturized system icon. Mousing up in 
a different location cancels the dis¬ 
miss operation. 

I merged elements from standard 
popup menus and Microsoft tool bars 
into the tear-off menu, and the result 
is the image shown in Figure 1. Since 
the tear-off menu displays a copy of 
the normal popup menu, a sizing 
border does not make sense; there is 
only one possible size and shape, 
that of the original popup menu. 1 
did create a small version of the 
standard caption bar (to display the 
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text of the associated menu item in the parent menu), but 
not as small as Word's or Excel's. The reason is that the 
caption text in Word and Excel requires a non-system 
font, and I don't want tearoff.dll to rely on a possibly 
nonexistent font. My compromise was to squeeze the sys¬ 
tem font into as small a vertical space as possible, and to 
use the small version of the system icon bitmap. This bit¬ 
map is exported from the video driver and can be ob¬ 
tained with the code: 

LoadBitmapCNULL. MAKEINTRESOURCE(OBM_CLOSE)); 

Clicking the system icon of a tear-off menu triggers the 
same behavior as a tool bar in Word or Excel. You can 
move a tear-off menu by dragging its caption bar. Unlike 
a tool bar, which can be dragged from any area outside 
of a button, a tear-off's non-caption area is completely 



Figure 2 The tear-off menu user interface in action 


filled with the menu image; clicking in the non-caption 
area makes a menu selection. Therefore a left mouse but¬ 
ton drag can only be initiated with a button down in the 
caption, tearoff.dll displays all tear-off menu windows 
owned by an active window as active (highlighted cap¬ 
tions); when the owner is inactive, tearoff.dll displays the 
tear-off menu windows as inactive. Clicking an inactive 
tear-off will activate its owner window. 

One crucial aspect of the tear-off menu user interface 
remains undiscussed: how do you tear off a menu? In 
Word and Excel, you can see a tool bar in the attached 
state, and can tear it off just by dragging. But a menu is a 
transient thing, not normally visible until you make a se¬ 
lection from the main menu bar. I thought about using a 
keyboard key in combination with the left mouse button 
to tear off the menu, but I really don't care for key¬ 
board/mouse combinations - they distract the user from 
the screen. So I chose to use the right mouse button. You 
can drop a menu by clicking on its associated menu item 
with the left button (this is normal Windows menu behav¬ 
ior). A subsequent click anywhere on the menu with the 
right button converts it to a tear-off menu. 

To reduce mouse clicks, I also put the tear-off in 'drag 
mode' immediately after you use the right mouse button 
to tear it off. This lets you convert it to a tear-off with a 
down click of the right mouse button, immediately drag it 
away, and finally drop it in its final position by releasing 
the mouse. Figure 2 (a through d) shows the four states 
involved as the user tears off and positions a menu. First, 
you display the menu you want to tear off. Second, you 
press the right button to turn that menu into a tear-off 
menu. Third, while the right button is still depressed, you 
can drag the menu to any screen position. Finally, when 
you release the right mouse button, you have a tear-off 
menu that you see and access while you continue to work 
in the application's main window. 

It didn't make much sense to allow the user to drag 
the tear-off with the right mouse button only at conver¬ 
sion time, so I added functionality for a drag operation 
that can be initiated by clicking anywhere on a tear-off's 
surface with the right mouse button. In fact, this can be 
done at any time the user is navigating through the menu 
with the left mouse button. So, for example, if you pull 
down a menu with a click and drag into it, then if you 
press the right button as well, the menu will be converted 
to a tear-off and the tear-off will be in drag mode. 

The Tear-Off API 

I tried to keep the application interface to tearoff.dll 
as simple as possible. To add tear-off menus to your exist¬ 
ing application, just follow these four easy steps: 

• Include tearoff.h (Listing 1) in your code. 

• For each window that is to support tear-off menus, 
place a call to FilterTearOffO at the beginning of the 
corresponding window procedure. 

• Wherever your code dynamically changes a menu at 
runtime (adding/removing checkmarks, disabling/ena¬ 
bling a menu item, etc.), add a call to UpdateTearOffsO. 
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• Link your program with the import library tearoff.lib, 
and make sure tearoff.dll is in your path when you 
execute your program (both tearoff.lib and tearoff.dll 
are on the code disk - see the table of contents page 
for availability). 

FilterTearOffO takes exactly the same arguments as a 
window procedure does, and I could have implemented it 
as a subclass procedure so that no changes would be re¬ 
quired to the client window procedure. But I decided not 
to for a couple of reasons. First, you may want control 
over which windows allow tear-off functionality. Second, 
and more important, subclassing is a dangerous activity to 
engage in (see the February 1994 'Practical C++' column 
for a discussion of some of the problems involved in 
safely subclassing windows). 

Although tear-off menus start working as soon as you 
add the call to FilterTearOffO, you need to use Up- 
dateTearOffsO to truly tear-off-enable your application. In 
a typical application, a menu's appearance can change as 
the state of the application changes. A prime example is 
the standard edit menu. If nothing is selected, the Copy 
and Cut menu items will be grayed out, otherwise they 
will be rendered normally. Normally this is no big deal; 
you call EnableMenuItemO when you notice a relevant 
change in state, and next time the user pulls down the 
edit menu, the menu manager shows the menu items in 
their new state. 

Things are a little more complicated when menus are 
no longer transient. Suppose the user has a selection (so 


Listing 1 tearoff.h — The tear-off menu API 


I* tearoff.h 

*/ 

/* -- Interface to tear-off menu module. 

*/ 

!★******★★★***★★★*****★******★★*★★★★*★★★******★*★**★**★* j 

1* Pass each window message to FilterTearOffO 
void WINAPI export FilterTearOfftHWND hwnd, UINT wm, 

*/ 

WPARAM wParam, LPARAM IParam); 


/* Call this function if you change an existing menu 
void WINAPI export UpdateTearOffstHWND hwnd, 

*/ 

HMENU hmnu); 


/* To destroy all of a window’s current tear-off menus. 
#define DestroyTearOffs(hwnd) \ 

*/ 

FilterTearOff(hwnd, WMJESTROY, 0, 0) 


/* These messages are sent to the menu owner. 

*/ 

/* wParam contains hwnd, LOWORD(lParam) contains 

*/ 

/* menu handle. (+100 to at least avoid colliding 

*/ 

/* with dialog messages) 

#define wmTearOffCreate (WMJJSER + 100) 

#define wmTearOffDestroy (WM USER + 101) 

/* End of File */ 

*/ 


Copy and Cut items are enabled on the Edit menu), tears 
off the Edit menu, and then removes the selection. The 
program notices and calls EnableMenuItemO (to disable 
Copy and Cut menu items), which changes the internal 
menu state, but what about the visual state of the tear-off 
menu? The visual state needs to be updated, else the user 
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will be perplexed that clicking on a valid-looking Copy 
menu item has no effect. UpdateTearOffsO addresses this 
problem. You call it after making changes to a popup 
menu. UpdateTearOffsO enumerates the current tear-off 
menus, and if it finds one for the given menu that is 


owned by the given client window, it updates the tear-off 
image to be in sync with the modified menu. 

There is one case in which you might have to rewrite 
your code to make tear-off menus work completely cor¬ 
rectly. The Windows menu manager sends a message 
( UM_INITMENUPOPUP) just before it displays a popup menu 


Listing 2 demotear.c — Tear-off menu demonstration program 


j★★*★*★★★**★*★**★★**★*★★*★★**★★★★*★★*★*★*★★*★★★★★★★★★★j 

/* demotear.c */ 

/* -- Program demonstrates tear-off menus. */ 

j★★*★★★***★★★★*★★★★★*★*★★**★★*★★★★**★★*****★★*★★★*★***j 

(/include <windows.h> 

((include "tearoff.h" 

const char szTitle[] = "Tear Off Menu Demo”; 

#i fdef_BORLANOC_ 

((pragma argsused 
((endif 

LRESULT CALLBACK _export LwWndProc(HWND hwnd, UINT wm, 
WPARAM wParam, LPARAM IParam); 

int PASCAL WinMainCHINSTANCE hins, HINSTANCE hinsPrev, 
LPSTR lpsz, int wShow) 

Jj 

/* -- Entry point. */ 

{ 

MSG msg; 

HWND hwnd; 
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If (NULL == hinsPrev) /* Main window class. */ 

{ 

WNDCLASS wcs; 
wcs.style = 0; 

wcs.lpfnWndProc = LwWndProc; 
wcs.cbClsExtra = 0; 
wcs.cbWndExtra = 0; 
wcs.hlnstance = hins; 

wcs.hlcon = LoadIcon(NULL, IDI_APPLICATION); 
wcs.hCursor = LoadCursortNULL, IDC_ARR0W): 
wcs.hbrBackground = (HBRUSH)(C0L0R_WIND0W + 1); 
wcs.lpszMenuName = "DemoTear"; 
wcs.lpszClassName = "DemoTear"; 
if (!RegisterClass(&wcs)) 
return FALSE; 

} 

msg.wParam = 0; 

if (NULL != (hwnd = CreateWindowC'DemoTear", 
szTitle, WSJVERLAPPEDWINDOW, CWJSEDEFAULT, 
CWJJSEDEFAULT, CWJSEDEFAULT. CWJSEDEFAULT, 

NULL, NULL, hins, NULL))) 

{ 

ShowWindowthwnd. wShow); 

while (GetMessaget&msg, NULL, 0, 0)) 

{ 

TranslateMessageUmsg); 

DispatchMessageUmsg); 

} 

} 

return msg.wParam; 


LRESULT CALLBACK _export LwWndProctHWND hwnd, 
UINT wn, WPARAM wParam, LPARAM IParam) 

/* -- Main window procedure 
/**** * *** ** ** ************** 

( 

HMENU hmnu; 
char szBuf[128]; 

UINT mid; 

Fi 1terTearOff(hwnd. wm, wParam, IParam); 

switch (wm) 

{ 

default; 

break; 

case WMJESTROY: 

PostQuitMessa ge(0); 
break; 

case WM_LBUTT0ND0WN: /* Pop a menu at the mouse. */ 
if (NULL = (hmnu = GetMenu(hwnd)) 11 
NULL = (hmnu = GetSubMenu(hmnu, 1))) 
break; 

Cl ientToScreen(hwnd, (LPPOINT)&1Param); 
TrackPopupMenuthmnu, TPMJEFTALIGN I 
TPMJEFTBUTTON, LOWORMIParam), 

HIWORD(lParam), 0, hwnd, NULL); 
break; 

case WMJOMMAND: 

if (IParam 1= 0 11 /* From a menu? */ 

NULL == (hmnu = GetMenu(hwnd))) 


*/ 

:***+*+*■*-*/ 
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that the user selected. Some applications don't update 
menu item states that have changed until they receive 
that message. If your application uses this kind of 'lazy 
updating,' you will have to do a bit of restructuring so 
that you update menus (and then call UpdateTearOffsO) 
when the item state actually changes, rather than waiting 
until the next UMJNITMENUPOPUP for that menu arrives. 

tearoff.h (Listing 1) also defines the macro 
DestroyTearOffsO. You do not need to call this explicitly, 
since tear-off menus are automatically destroyed when 
their parent windows are destroyed. This macro just 
makes it easy to quickly destroy all of a window's tear-off 
menus at any time, giving you a little more control over 
the user interface. The DestroyTearOffsO macro calls Fil- 
terTearOffO with a UM_DESTROY message, tricking it into 
cleaning up as though the client window were dying. 

The final two components of the tear-off menu API are 
the messages mTearOffCreate and wmTearOffDestroy. 
tearoff.dll sends these messages to the owner window 
each time it creates or destroys a tear-off menu window. 
The window handle and the menu handle are supplied 
with the message's wParam and 1 Pa ram parameters. As with 
DestroyTearOffsO, you can ignore this part of the API; it's 
just there to give you a little more control over the user 
interface. 

demotear.c (Listing 2) is a simple demonstration program 
that provides tear-off menus by making use of Fil- 
terTearOffO and UpdateTearOffsO. demotear.exe has three 
menu items on its menu bar (see Figure 2), created by the 
resource file in demotear.rc (Listing 3). 

The first two items have popup 
menus. The last is a simple menu 
item that calls DestroyTearOffsO to re¬ 
move all tear-offs belonging to the 
main window. The first popup has a 
list of four menu items; it keeps a 
checkmark on the last one picked to 
demonstrate dynamically updating a 
tear-off menu. The second popup has 
one menu item and a submenu, 
which has a submenu, and so on for 
four levels. 

demotear.exe' s main (and only) win¬ 
dow procedure, LwUndProcO, calls Fil- 
terTearOffO before falling into its 
message switch statement. On a left 
mouse button down, LwUndProcO cre¬ 
ates a copy of the second popup at 
the current mouse location, using 
TrackPopupMenuO. I did this to show 
that even menus created with Track¬ 
PopupMenuO can be torn off, although 
they will have no titles in their cap¬ 
tions. In LwTearProcO' s UM_COMMAND 
case, if a menu item from the first 
popup was picked, the checkmark is 
moved to the new location, and Up¬ 
dateTearOffsO is called to reflect the 
change if the menu has been torn 


off. In addition, LwUndProcO displays a message box to 
show which menu item was picked. 


Listing 2 continued 


break; 

if (wParam >= 1801 &8 wParam <= 1004 U 
NULL != (himu = GetSubMenu(hmnu, 0))) 

{ 

for (mid = 1001; mid <= 1004; midH-) 
CheckMenuItem(hmnu. mid, MFJYCOkHAND I 
(mid ** wParam ? 

MF_CHECKEO ; MFJJNCHECKED)); 
UpdateTearOffs(hwnd. himu); 

} 

if (wParam == 1009) 

DestroyTearOffs(hwnd); 
el se 

{ 

wsprintf(szBuf, "Menu item %d picked.". 
wParam ■ 1000); 

MessageBoxthwnd. szBuf, szTitle, MB_0K); 

} 

break; 

} 

return DefWindowProcIhwnd, wm, wParam, IParam); 

) 

/* End of File */ 
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Normal Menu Message 
Flow 

To understand how tearoff.dll 
works, it is instructive to trace the 
flow of events that occur when you 
use a standard popup menu. I will 
describe the scenario when the user 
presses the left mouse button over a 
menu item (in a menu bar) that has 
an associated popup menu. Assume 
that the application passes non-client 
and menu-related UM_SYSCOMMAND mes¬ 
sages through to DefUindowProcO, as 
most applications do. Figure 3 shows 
a simple textual depiction of the 
function calls and window messages 
that this section discusses. 

You might think that GetMessageO 
does little more than copy messages 
from a queue and decrement a 
queue pointer. In fact, GetMessageO 
takes an active part in implementing 
parts of Windows' standard message 
flows. After a mouse down on the 
menu item in the menu bar, GetMes¬ 
sageO will see a button-down event 
in the queue and begin to take ac¬ 
tion. It first sends a UM_NCHITTEST to 
the topmost window under the 
mouse to determine which part of 
the window was clicked. DefUindow- 
ProcO returns HTMENU (or HTSYSMENU if 
the system menu was clicked). Get¬ 
MessageO then sends a UMJETCURSOR 
message to ensure that the cursor is 
the correct shape (the default is an 
arrow). Finally, GetMessageO returns a 
VMJCLBUTTONDOUN message to the 
caller (if the click had occurred in the 
client area, this would have been a 
UM_LBUTT0ND0UN message). 

The application will eventually call 
DispatchMessageO to send the event 
to the window clicked on. DefUindow- 
ProcO, seeing a mouse down in the 
menu bar, will send a UM_SYSCOMMAND 
to the window owning the menu bar 
(let's assume it's the application's 
main window). The accompanying 
wParam value will be SC_MOUSEMENU. 
When DefUindowProcO is reentered 
with this UMJYSCOMMAND, it will be on 
the path to 'menu mode,' a modal 
message loop. DefUindowProcO will 
not return from the loop until the 
user dismisses the menu. 

Just before entering the modal 
message loop, the menu manager 


sends several messages to the win¬ 
dow procedure. First is the undocu¬ 
mented UM_ENTERMENULOOP message. 
Next is a UM_SETCURSOR message (once 
again to ensure the cursor is the right 
shape), which is followed by a 
UM_INITMENU message. The application 
may process UM_INITMENU if it wishes, 
even though the wParam in the mes¬ 
sage contains the menu bar's menu 
handle, not a popup menu handle. 
The next message generated by the 
menu loop initialization code is 
UMJENUSELECT. This message identifies 
which item on the menu bar was 
clicked by the user. 

Because the clicked menu item 
has a corresponding popup menu, 
the menu manager will also generate 
a UM_INITMENUPOPUP message. This is 
generally more useful than UM_INIT- 
MENU, since the popup menu is not yet 
visible, it gives the application an op¬ 
portunity to set the menu's state (an 
alternative to reacting to an applica¬ 
tion state change and immediately 
updating the menu). To continue the 
earlier example, when an application 
that uses this alternative method re¬ 
ceives a UM_INITMENUPOPUP, it checks to 
see if there is any selection, and 
grays or enables the Cut and Copy 
items on the edit popup menu. This 
type of lazy update does not coexist 
well with a tear-off menu. Users will 
want to see an accurate depiction of 
available menu choices all the time, 
not just when they've clicked on the 
tear-off. You will have to do some 
extra work to restructure your appli¬ 
cation to react to changes in state if 
you are currently using lazy menu 
item updates. 

By default, the menu manager al¬ 
ways highlights the first item on a 
popup menu when the menu is first 
dropped. It lets the application know 
it has done this by sending a 
UM_MENUSELECT message, this time for 
the popup menu. At this point, the 
menu manager makes visible a spe¬ 
cial window that contains the popup 
menu; for this purpose, the menu 
manager maintains one popup menu 
window that is never destroyed. The 
window class name of this window is 
'#32768,' as documented in the Tech 
Article "Classy Windows,' dated June 
23, 1993 on the MSDN CD-ROM. If the 
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popup menu to be displayed is not a 
submenu of another popup menu, 
the menu manager uses this always- 
present window to display the menu. 
Otherwise, if the popup menu is a 
submenu, the menu manager creates 
a new window of class '#32768'. Re¬ 
gardless of which window is dis¬ 
played, the menu manager will then 
send a UM_ENTERIDLE message to the 
menu's owner window, to allow the 
application to perform any necessary 
idle processing. 

From this point on, the menu 
manager is inside its modal message 
processing loop. Each time it gets a 
message from the input queue, it 
sends an additional UM_ENTERIDLE mes¬ 
sage to the application. Additional 
UM_MENUSELECT messages (each accom¬ 
panied by a subsequent UM_ENTERIDLE 
message) will be sent if the user 
highlights different menu items, if the 
popup contains submenus, additional 
UMJNITMENUPOPUP messages are also 
possible. 

Once the user dismisses the menu, 
either by making a selection or can¬ 
celing the menu, the menu manager 
code on the other side of the loop 
sends another undocumented mes¬ 
sage, MM_EXITMENULOOP. If the user 
made a selection, the menu manager 
also posts a UM_COMMAND (or UM_SYSC0M- 
MAND, if an item on the system menu 
was picked) message with the menu 
ID of the selected menu item. 

incidentally, I used Nu-Mega's 
Bounds-Checker v2.0 to trace the ex¬ 
ported Windows function calls in¬ 
voked during a popup menu drop 
operation. This version of Bounds- 
Checker comes with a trace analysis 
program, tview.exe, that uses a nice 
graphical presentation to show mes¬ 
sage flow, including return values 
and reentrant calls. It was quicker 
and more convenient to track the 
message flow using these tools than 
by the more traditional way of set¬ 
ting breakpoints with a debugger. 

Lower-Level Functions 

In order to help split this article 
and its code into two even parts, I 
will postpone a top-down discussion 
of the code in tearoff.dll until the 
next issue (April 1994). The rest of 
this article covers the central data 
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Listing 3 demotear.rc — Resource file for 
demotear.exe 


^ ***************************************************** j 

/* demotear.rc */ 

/* -- Menu for tear-off menus demo. */ 

^★★★★★★★★★★★★★★★★★★★★★★★****************************** j 

//include <windows.h> 

DemoTear MENU 
BEGIN 

POPUP "Popup 41" 

BEGIN 

MENUITEM "Menu Item 41". 1001, CHECKED 
MENUITEM "Menu Item 42", 1002 
MENUITEM "Menu Item 43", 1003 
MENUITEM "Menu Item 44", 1004 
END 

POPUP "Popup 42" 

BEGIN 

MENUITEM "Menu Item 45", 1005 
POPUP "4Submenu" 

BEGIN 

MENUITEM "Menu Item 46", 1006 
POPUP ”4Submenu" 

BEGIN 

MENUITEM "Menu Item 47", 1007 
POPUP "4Submenu" 

BEGIN 

MENUITEM "Menu Item 48”, 1008 
END 
END 
END 
END 

MENUITEM "4Destroy Tear-offs" 1009 
END 


structure and some of the utility functions in the tear-off 
menu code. 

tearutil.h (Listing 5) contains most of the declarations 
for the tear-off menu code, i use a data structure called 
TOS (for Tear-Off State) to represent information about 
each tear-off menu window that exists at any given time. 
Table 1 describes the fields in the TOS structure, tearutil.h 
also declares the internal functions in tearoff.dll. tearu- 
til.c (Listing 6) contains some of the lower-level functions 
used to implement tear-off menus. 

Tear-off menu windows have captions, and i try to set 
the caption text equal to the text of the menu item the 
user selected to pull down the original menu (see Figure 2 
for an example of this). Trying to locate this menu item 
text is a real pain because the Windows API does not pro¬ 
vide a way to obtain a parent menu handle given a 
popup menu handle. Instead, I have to walk the entire 
menu hierarchy looking for a specific popup menu at a 
specific location in the parent menu. This is done by the 
helper routine HmnuFindO in tearutil.c. I got lazy and im¬ 
plemented HmnuFindO using recursion, which I generally try 
to stay away from (after all, the stack is a limited re¬ 
source). However, menus are rarely nested very deep, and 
besides, recursion makes for a simpler implementation. 

Another low-level function in tearutil.c is PaintSysI- 
con(), which renders the little system icon (see Figure 1) in 
either the normal or highlighted state. One of its parame¬ 
ters is the device context to draw to. If NULL is passed for 
the device context handle (which is useful during mouse 
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tracking), PaintSysIconO will allocate one. It uses 
StretchBltO to display the system icon bitmap in case the 
driver exports a bitmap that is not the same height as the 
system font. The icon might look a little grainy in that 
case, but it requires little code and is better than nothing. 
Another argument to PaintSysIconO is the pointer to the 
TOS structure that represents the tear-off menu. If the 
grftos member in the TOS structure has the ftosHilite flag 
set, then PaintSysIconO uses the NOTSRCCOPY raster opera¬ 
tion code to paint an inverted image; otherwise, it uses 
SRCCOPY to paint an unaltered image. The routine then se¬ 
lects a NULL brush into the device context and uses Rectan¬ 
gle.0 to draw a frame around the miniature system icon. 
Finally, if PaintSysIconO had to allo¬ 
cate a device context, it releases it. 

DrawGhost is not a very pretty sight. 

Suffice it to say it draws a hollow rec¬ 
tangle with each side three border 
units thick. It uses the PATINVERT raster 
operation code to achieve an XOR 
between the brush and the screen 
pixels. It currently uses the 
DKGRAYJRUSH stock object, but this 
does not quite match what Windows 
uses when dragging an outline. You 
might want to do some experimenta¬ 
tion here to get it exactly right. 

BeginSnapO 

As I mentioned earlier, tearoff.dll 
performs its magic by snapping a bit¬ 
map image of the pulldown menu at 
the moment that the user tears the 
menu off by pressing the right mouse 
button. As Figure 1 and Figure 2 
show, the menu manager selects the 
first menu item when it first displays 
a popup menu. BeginSnapO's job is to 
remove the selection, so that the 
menu image is suitable for storing in 
the future tear-off's offscreen bitmap. 

I think it would look strange to show 
a selection in a tear-off; the user 
should only see a selection while in¬ 
teracting with the menu. It turns out 
that there is a simple way to trick the 
menu manager into unselecting the 
first menu item. 

If you look closely at any popup 
menu, you will notice that there is a 
thin border surrounding the menu (as 
well as a shadow on the bottom and 
right edges). If you are dexterous (or 
perhaps lucky) enough to click this 
tiny border with the mouse, the 
menu manager deselects the selected 
menu item but does not dismiss the 
menu. BeginSnapO exploits this be¬ 
havior. It obtains the rectangle from 


the menu's window, the handle of which is the third pa¬ 
rameter to BeginSnapO. The routine then fakes a click on 
the border by posting a UM_LBUTT0ND0UN, UM_LBUTTONUP pair to 
the menu window's origin. It's important to note that 
these messages must be posted and not sent. This is be¬ 
cause the menu manager does most of its work, including 
processing mouse messages, inside the menu loop, not in 
the window procedure. If you send a message, it never 
appears in the task queue, and therefore is never seen 
inside the menu manager's message loop. 

The problem with posting messages to emulate the 
mouse click is that, because they are posted, not sent, 
those messages will not arrive until control returns to the 
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Figure 3 Standard pulldown menu message flow 


GetMessage(...) 

SendMessaget... WMJCHITTEST ...) 

MyWindowProct... WMJCHITTEST ...) 

DefWindowProct... WMJCHITTEST ...) 

<-— (returns HTMENU) 

SendMessageC... WMJETCURSOR ...) 

MyWindowProc(... WMJETCURSOR ...) 

<-- GetMessage returns a WMJCLBUTTONDOWN message 
DispatchMessaget... WMJCLBUTTONDOWN ...) 

MyWindowProc(... WMJCLBUTTONDOWN ...) 

DefWindowProct... WMJCLBUTTONDOWN ...) 

SendMessageC.. WMJYSCOMMAND, SCJOUSEMENU ...) 
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<Windows menu manager gets called) 

(for brevity, calls to window proc not shown) 
SendMessageC.. WMJNTERMENULOOP ...) 
SendMessageC.. WMJETCURSOR ...) 

SendMessageC.. WMJNITMENU ...) 

SendMessageC.. WMJENUSELECT ...) 

SendMessageC.. WMJNITMENUPOPUP ...) 
SendMessageC.. WMJENUSELECT ...) 

<menu manager displays popup menu, enters message loop) 
+- -> 

I GetMessageC..) 

I SendMessageC.. WMJNTERIDLE ...) 

I DispatchMessaget...) 

+---+ 

SendMessageC.. WMJXITMENULOOP ...) 

/* post command user selected */ 

PostMessaget... WMJOMMAND ...) 

<menu manager returns to DefWindowProcO, etc.) 
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Listing 4 

demotear.exe 

demotear.h — Header file for 

/***************************************************** j 

1* demotear.h 

*1 

/* -- Menu constants for tear-off menus demo. */ 

/***************************************************** j 

(/define idmTearOff 

1 /* Main menu id. */ 

//define midDummyl 

1001 

//define midDummy2 

1002 

//define midDummy3 

1003 

//define midDummy4 

1004 

//define midDummy5 

1005 

//define midDummy6 

1006 

//define midDummy7 

1007 

//define midDummy8 

1008 

//define midDummy9 

1009 

//define midDummyl0 

1010 

//define midDummyll 

1011 

//define midDummyl2 

1012 

/* End of File */ 



menu manager's message loop, but tearoff.dll needs to 
regain control after the mouse messages are processed so 
that it can snap an image of the menu. The solution is to 
post another message after the mouse down and mouse 
up, one that is only understood by tearoff.dll's code. 
Posted messages are placed in the task's local queue. By 
the time this private message has been received, the 
menu manager's message loop will have seen the mouse 
click messages and removed the unwanted highlight from 
the selected menu item. The menu manager will then dis¬ 
patch the private message posted by BeginSnapO to the 
message's target (the window that owns the menu), where 
tearoff.dll's main API function, FIlterTearOffO, will re¬ 
ceive it. 

I had to be careful about which window message num¬ 
ber to use for this private window message, tearoff.dll 
cannot know which private messages are already being 
used by its clients. It would be a disaster to hard-code 
some arbitrary value (UM_USER plus some offset) for 
tearoff.dll's private message, only to have it coincide 
with a message value being used by a client. This is 
where the Windows API function RegisterUindowMessagef) is 
useful. Given a (hopefully unique) string, it returns a 
unique message value in the range 0xc000 through 0xffff 
for all windows in the system. Window procedures using 
hard-coded message values are restricted to UM_USER 
( 0x0400) through 0x7fff. Unless the client has also called 
RegistersndowMessagef) with the exact same string (or is 
not playing by the rules and is using constant message 
values greater then 0xbfff), the message will pass through 
the client window procedure without causing harm. During 
initialization, tearoff.dll calls RegisterUindowMessageO and 
the returned value is stored in the global variable mPrivate. 

BeginSnapO's last act is to package its first parameter, 
the TOS pointer, and the menu window handle into a 
mPrivate message. It posts this message to the recipient 
window, specified in BeginSnapO's second parameter, 
which in this case is the menu's owner window. After Be¬ 
ginSnapO returns, the menu is ready to be snapped (by 
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copying its screen image to a mem¬ 
ory bitmap), tearoff.dll will get a 
chance to do just that when the pri¬ 
vate window message posted by Be- 
ginSnapO gets dispatched by the 
menu manager message loop. 

EndSnapO 

The final utility function in tearu- 
til.c is EndSnapO, which tearoff.dll 
will call when it receives the private 
message posted by BeginSnapO. 

EndSnapO completes the processing 
initiated with BeginSnapO. EndSnapO 
assumes that other code has already 
created the window that is to contain 
the tear-off menu. It repositions and 
resizes that window to be the same 
size as the menu about to be torn 
off, and it captures the menu's screen 
image in an offscreen bitmap that 
the tear-off menu window uses to 
paint itself. The reason EndSnapO does not create the tear- 
off menu window itself is so that tearoff.dll can call it 
both when the menu is first torn off, and when, if the 
client program calls UpdateTearOffsO, a change is to be 
made in an existing tear-off menu window, tearoff.dll 
passes a flag to EndSnapO that indicates whether the tear- 
off menu window is being newly created or is being reini¬ 
tialized because of a change to the menu state. 

EndSnapO first uses SetWindowPosO to move, size, and 
show the tear-off window. At the same time, if this is a 
new tear-off menu window, EndSnapO withholds passing 
the SUP_N0Z0RDER flag so that SethlindowPosO will bring the 
window to the top as well. 

After repositioning and resizing, EndSnapO calls Invali- 
dateRectO, for reasons that require a bit of a digression. 
As 1 mentioned earlier, Windows' menu manager uses 
windows of class "#32768' to contain the menus that it 
draws. That window class is registered with the CS_SAVEBITS 
style. This style is useful for transient windows such as 
menus, as it directs Windows to keep an offscreen copy of 
the bits present before the window is displayed, and to 
restore them to the screen after the window is destroyed 
(as long as the window's position has not changed). This 
optimization saves having to generate UM_PAINT messages 
for any underlying windows. In this case, the feature is 
actually a hindrance. The reason is that the tear-off menu 
window has just been positioned on top of all the under¬ 
lying windows, so if Windows restores the image that lies 
beneath the menu, it will be painting underlying windows 
on top of the new tear-off menu window. To deal with 
this problem, EndSnapO calls InvalidateRectO for the tear- 
off's entire window, which causes Windows to discard the 
saved bits originally covered by the menu. 

To terminate menu mode, EndSnapO posts another 
UM_LBUTT0ND0HN, UM_LBUTTONUP pair to the menu window, but 
this time for the coordinate that is one pixel above and to 
the left of the menu window's origin, simulating a mouse 


Table 1 Members of TOS (Tear-Off State) structure 

grftos 

a group of flags that describe various modes the tear-off menu can be in: 

ftosTearMenu indicates that an actual menu is present on top of the 
tear-off menu window. 

ftosActive controls whether the tear-off menu window caption is 

drawn as active or inactive. 

ftosHilite TRUE when user has depressed mouse button over tear- 

off menu window system icon, and mouse is still over 
the system icon (so it should be highlighted). 

ftosDrag TRUE while user is dragging a tear-off menu window. 

ftosOn TRUE while ghost frame (used during dragging) is visible 

(must be XOR-ed again to move or erase it). 

Pt 

last location of mouse during dragging. 

dpt 

offset of the original mouse position when dragging began. 

szTitle 

text of the tear-off menu window caption (a variable-length field). 


click outside of the menu, which causes the menu man¬ 
ager to remove the menu and leave menu mode (once 
the menu loop receives the posted messages). 

The next chunk of code in EndSnapO removes the tear- 
off menu window's old bitmap, if it had one (remember, 
EndSnapO gets called to update existing tear-offs, not just 
new ones), creates a new bitmap, and initializes the bit¬ 
map with the menu's screen image. The last chunk of 
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code checks to see if the right mouse button is down dur¬ 
ing creation of a new tear-off, and posts a MM_RBUTT0ND0HN 
to the tear-off menu window if so, to automatically shift to 
drag mode. 

When EndSnapO returns, the tear-off menu window has 
been completely initialized. The tear-off menu window still 
has to paint itself, but it will be receiving a WM_PAINT mes¬ 
sage, since EndSnapO's call to SetUindowPosO made the win¬ 
dow visible, and therefore in need of an update (not to 


mention the call to InvalidateRectO that was needed to 
blow away the saved bits). 

Next Month 

So far, I have outlined the general scheme for imple¬ 
menting tear-off menus, presented the simple API you use 
to add them to your program, and explained some of the 
essential low-level functions that tearoff.dll uses to get the 
job done. Next month, I will provide a top-down description 


- 

Listing 5 tearutil.h — Header file for tear-off menu code 

♦define OEMRESOURCE /* To get 08M bitmaps. */ 


♦Include <windows.h> 

LRESULT CALLBACK export LwSubclassProc(HWND hwnd, 

♦include <windowsx.h> 

UINT wm, WPARAM wParam, LPARAM IParam); 

♦include "tearoff.h" 

LRESULT CALLBACK export LwTearProc(HWND hwnd. 


UINT wm, WPARAM wParam. LPARAM IParam); 


int CALLBACK LibMainiHINSTANCE hinsThis, WORD ds. 

enum /* Flags, Tear-Off State. */ 

WORD cbHeap, LPSTR lpsz); 

i 

Int CALLBACK _export WEP(lnt); 

ftosNil = 0x00, /* Nothing special. */ 


ftosTearMenu = 0x01, /* Tear-off menu active. */ 

♦define HwndMenuCurO FIndW1ndow(szMenuClass. NULL) 

ftosActive = 0x02, /* Tear-off Is active. */ 

♦define FSetWndPtos(hwnd. ptos) \ 

ftosHIlite = 0x04, /* System Icon is hilited. */ 

SetProp(hwnd, szMenuTag, (HANDLE)(ptos)) 

ftosDrag = 0x08, /* Tear-off being dragged. *7 

♦define PtosAlloc(cch) \ 

ftosOn = 0x10 /* Ghost is XOR'ed on. */ 

((PTOS)Local Alloc(LPTR, cch + sizeof(struct TOS))) 

}; 

fdefine PtosRemoveWnd(hwnd) \ 


((PTOS)RemoveProp(hwnd. szMenuTag)) 

typedef struct TOS /* Tear-Off State */ 


{ 

void BeginSnapCPTOS ptos, HWND hwndPop. HWND hwndMenu, 

struct TOS ‘ptosNext; /* Next in list. */ 

UINT wmPrivate); 

HMENU hmnu; /* Popup menu handle. */ 

void DrawGhost(PTOS ptos); 

HBITMAP hbmp; /* Offscreen bitmap. */ 

void EndSnap(PTOS ptos, HWND hwndMenu, BOOL fNew, 

HWND hwnd; /* Tear-off window. */ 

int dyText, HDC hdcMem); 

HWNO hwndOwner; /* Menu owner window. */ 

void FreeTos(PTOS ptos); 

enum FTOS grftos; /* Menu Data State. */ 

HMENU HmnuFind(HMENU hmnuTop, HMENU hmnu, Int imnu); 

POINT pt; /* Ghost drag location. */ 

void PaintSysIconlPTOS ptos, HDC hdc, HOC hdcMem, 

POINT dpt; /* Drag offset. */ 

HBITMAP hbmpSys, int dyText, BITMAP bmpSys); 

char $zTitle[l];/* For title bar. */ 

/* End of File */ 

) TOS. *PT0S; 



Listing 6 tearutil.c — Low-level tear-off menu utility functions 


♦include "tearutil.h" 

HBITMAP hbmpSav; 


HBRUSH hbrsSav; 

HMENU HmnuFind(HMENU hmnuTop. HMENU hmnu, int imnu) 

BOOL fRelease = FALSE; 

/*****************************************************j 


/* -- Given a popup menus index within its parent, */ 

If (NULL == hdc) 

/* return its parent menu handle. */ 

i 

/* -- hmnuTop : Current menu under consideration. */ 

if (NULL == (hdc = GetDC(ptos->hwnd))) 

/* -- hmnu : Find this popup menu’s parent. */ 

return: /* Give up. */ 

/* -- imnu : Popup’s Index within parent. */ 

fRelease = TRUE; 

{ 

hbmpSav = SelectObject(hdcMem, hbmpSys); 

int cmnu, imnuT; 

StretchBltlhdc, 8. 8. dyText, dyText, hdcMem. 

HMENU hmnuT; 

bmpSys.bmWidth, 0. bmpSys.bmWidth, 


bmpSys.bmHeight. (ptos->grftos 4 ftosHi1ite) ? 

If (NULL « hmnuTop) 

NOTSRCCOPY : SRCCOPY); 

return NULL; 

if (NULL != hbmpSav) 


SelectObject(hdcMem, hbmpSav); 

/* Is the current top level menu the parent? */ 

hbrsSav = SelectObj ect(hdc. 

cmnu = GetMenuItemCount(hmnuTop); 

GetStockObject(NULL BRUSH)); 

for (imnuT = 0; ImnuT < cmnu; imnuT++) 

RectangleChdc. 0, 8. dyText + 1, dyText + 1): 

{ 

if (NULL != hbrsSav) 

if ((hmnuT = GetSubMenu(hmnuTop, ImnuT)) == 

SelectObject(hdc, hbrsSav); 

hmnu && imnu == imnuT) 

if (fRelease) 

return hmnuTop; 

ReleaseDC(ptos->hwnd, hdc); 

If (NULL != (hmnuT = HmnuFind(hmnuT, hmnu, 

) 

imnu))) 


return hmnuT; 


i 

void BeginSnapIPTOS ptos. HWND hwndPop. HWND hwndMenu, 


UINT wmPrivate) 

return NULL; 

/*****************************************************/ 

i 

/* -- Prepare the menu to have its picture taken. */ 


/* -- Unselects any selected menu item. */ 

void PaintSysIcon(PTOS ptos, HDC hdc, HDC hdcMem, 

/* -- ptos : Tear-off. */ 

HBITMAP hbmpSys. int dyText. BITMAP bmpSys) 

/* -- hwndPop : Window to pop menu on. */ 

/*****************************************************/ 

/* -- hwndMenu : USER’S menu window. */ 

/* -- Paint the small system-menu icon. */ 

/* -- wmPrivate : Our reserved private message ♦ */ 

/* -- ptos : Get state from here. */ 

/ ****************** ****************•*.****★************* / 

I* -- fLit : Hllite bitmap if set, else normal. */ 

( 

t 

RECT rect: 
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of the remaining code in tearoff.dll, explaining how it 
modifies the normal menu message flow to accomplish its 
ends, and presenting the remaining code. The complete 
source and binary code for tearoff.dll resides on both 
this month's and next month's code disk, so you don't 


have to wait until next month to add tearoff menus to 
your application. This archive is also available separately 
in file tomenu.zip in Library 7 (R&D Publications) in forum 
CLMFORUM on CompuServe. □ 


Listing 6 continued 


/* Unselect selected menu item. */ 

GetWindowRect(hwndMenu, irect); 
PostMessagediwndMenu. WM_LBUTT0ND0WN, 0. 

*(LPARAM *)&rect.left); 

PostMessage(hwndMenu, WM_LBUTTONUP, 0, 

♦(LPARAM *)irect.left); 

/* By the time this is received, menu will have */ 
/* no selection. */ 

PostMessage(hwndPop, wmPrivate, (WPARAM)hwndMenu, 
MAKELONG(ptos, 0)); 

} 

void EndSnap(PTOS ptos, HWND hwndMenu, BOOL fNew, 
int dyText, HDC hdcMem) 

/*****************************************************/ 


/* - 

- Capture the popped menu's image into the tear- 

*/ 

(LPARAM)(LPPOINT)irect); 

/* 

off's offscreen bitmap. 

*/ 


/* - 

- Resize the tear-off to the menu’s size. 

*/ 

/* Get a bitmap for the tear-off. If this stuff */ 

/* - 

- ptos 

Tear-off. 

*/ 

/* fails, things will be ugly but won’t blow up. */ 

/* - 

- hwndMenu 

USER'S menu window. 

*/ 

if (NULL != ptos->hbmp) /* Nuke old one. */ 

/* - 

- fNew 

If set, indicates tear-off was 

*/ 

DeleteObject(ptos->hbmp); 

/* 


newly created. Begin drag if so. 

*/ 

if (NULL != (hdc = GetDC(hwndMenu))) 

/* - 

- dyText 

system font height. 

*/ 

{ 

/* - 

- hdcMem 

Memory device context 

*/ 

if (NULL != (ptos->hbmp = 


/*****************************************************/ 

{ 

HDC hdc; 

HBITMAP hbmpSav; 

RECT rect; 

POINT pt; 
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GetWindowRect(hwndMenu. &rect); /* Reposition. */ 
pt.x = rect.right - rect.left; /* tear-off. */ 
pt.y = rect.bottom - rect.top; 
SetWindowPos(ptos->hwnd, HWND_T0P, rect.left, 
rect.top - dyText, pt.x. pt.y + dyText, 
SWPJHOWWINDOW I SWPJOACTIVATE I 
(fNew ? 0 : SWPJOZORDER)); 

/* Blow away the saved menu bits. */ 

InvalidateRect(ptos->hwnd. NULL. FALSE); 

/* Cancel menu mode. */ 

InflateRect(&rect, -1, -1); 

PostMessagediwndMenu, WM_LBUTT0ND0WN. 0, 

(LPARAM)(LPPOINT)&rect); 

PostMessage(hwndMenu. WM_LBUTTONUP. 0. 


CreateCompatibleBitmapdidc, pt.x, pt.y))) 

{ 

hbmpSav = SelectObject(hdcMem. ptos->hbmp); 
BitBltdidcMem, 0, 0. pt.x, pt.y, hdc, 0, 0. 

SRCCOPY); /* Capture bits. */ 
if (NULL != hbmpSav) 

SelectObject(hdcMem, hbmpSav); 

} 

ReleaseDC(hwndMenu, hdc); 

} 

if (fNew M GetKeyState(VK_RBUTTON) < 0) 

{ /* Force tear-off into drag mode. */ 
GetCursorPosUpt); 

ScreenToClient(ptos->hwnd, &pt); 
PostMessage(ptos->hwnd, WM_RBUTTONDOWN. 0. 
♦(LPARAM *)&pt); 


} 


void DrawGhost(PTOS ptos) 

/*****************************************************/ 
/* -- Invert the ghost frame at its current drag */ 
/* location. */ 

/*****************************************************/ 

{ 

HBRUSH hbrsSav; 

RECT rect; 

int dxBdr = 3 * GetSystemMetrics(SM_CXBORDER); 
int dyBdr = 3 * GetSystemMetrics(SM_CYBORDER); 
int dyT; 

POINT pt; 

HDC hdc; 

if (NULL == (hdc = GetDC(NULL))) 
return; 

ptos->grftos A = ftosOn; 
hbrsSav = SelectObject(hdc, 
GetStockObject(DKGRAYJRUSH)); 
GetClientRect(ptos->hwnd, &rect); 
pt.x = ptos->pt.x - ptos->dpt.x; 
pt.y = ptos->pt.y - ptos->dpt.y; 

PatBlt(hdc, pt.x. pt.y. rect.right, dyBdr, 
PATINVERT); 

PatBlt(hdc, pt.x, pt.y + rect.bottom - dyBdr, 
rect.right. dyBdr, PATINVERT); 

PatBlt(hdc, pt.x. pt.y += dyBdr, dxBdr, 
dyT = rect.bottom - 2 * dyBdr. PATINVERT); 

PatBlt(hdc, pt.x + rect.right - dxBdr, pt.y, 
dxBdr, dyT. PATINVERT); 

SelectObj ect(hdc. hbrsSav); 

ReleaseDC(NULL, hdc); 

) 

/* End of File */ 
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A Windows NT C++ Class 
for Asynchronous I/O 

Paula Tomlinson 


With Windows NT offering a preemptive, multithreaded environment for 
Windows programs, and the next update to Windows 3.1 ('Chicago') planning 
to offer the same (according to published reports), it's no wonder that many 
articles about writing multithreaded Win32 programs have appeared during the 
last year. All these articles may still leave you wondering just how your own 
specific application could benefit from a multithreaded operating system, 
though. Since multi-processor systems are still expensive and scarce, your appli¬ 
cation will most likely execute on a single-processor machine, and simply divid¬ 
ing the program into multiple threads can result in multiple threads competing 
for the same processor with no increase in throughput. 

One place that a preemptive, multithreading operating system can produce 
measurable performance improvements (even on single-processor machines) 
for many programs is during device I/O. When a DOS program issues a file 
read or write request, everything pretty much grinds to a halt from the time the 
device begins processing the I/O until the I/O completes and control returns to 
the caller. Under Win32, however, the operating system can continue to do 
useful work (such as executing other processes) while waiting for a device to 
complete an I/O request. If you restructure your program to use asynchronous 
I/O, your program can also perform other tasks while waiting for I/O to com¬ 
plete. 

Unlike some uses for multithreading, asynchronous I/O offers clear opportu¬ 
nities for making your program more efficient. Some devices, such as a CD- 
ROM, can take the biggest part of a second to complete an individual I/O 
request, enough time for your program to perform a large amount of process¬ 
ing. However, even the fastest hard-disk drive is still usually an order of magni¬ 
tude slower than CPU speeds, making most file I/O potentially worth exploiting 
as an asynchronous activity. For example, if your Win32 program reads a file 
of records and processes them one at a time, it could overlap (asynchronous 
I/O is sometimes called overlapped I/O) the processing of one batch of records 
with an I/O request to read the next batch, potentially reducing the time re¬ 
quired to process the file to roughly the time required to read the file. 


Paula Tomlinson received an Electrical Engineering degree from Colorado State Univer¬ 
sity. For the past six years she has developed various DOS, Windows and Windows 
NT-based drivers and commercial applications for the HP ScanJet scanners, the HP 
LaserJet Fax and the HP DeskJet printers. She is currently working on a book tenta¬ 
tively titled Writing Device Drivers for Windows NT. The opinions expressed in this 
column are hers alone and do not necessarily reflect the opinions of Hewlett-Packard. 
Send questions or correspondence to Paula via internet as paulat@vcd.hp.com. 
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Windows NT supports multiple installable file systems, 
and not all file systems support all Win32 features. For 
example, currently only NTFS supports file security. How- 
ever, all three major file systems (FAT, HPFS, and NTFS) 


support asynchronous I/O. This article describes how asyn¬ 
chronous I/O works under Win32 and provides a C++ 
class (CFilelO) that implements asynchronous file I/O. The 
code disk (see the table of contents for availability) con¬ 
tains a demonstration program that 
monitors a spool directory and asyn¬ 
chronously copies to the printer any 
files that appear in that directory. 
(See the sidebar 'Asynchronous I/O: 
Behind the Scenes' for an overview 
of NT's processing of asynchronous 
I/O operations.) 

Win32 File I/O Functions 

Win32 provides a complete set of 
file and directory routines that are 
somewhat different than the analo¬ 
gous DOS routines. Table 1 shows 
the rough correspondences between 
the Win32 file and directory API and 
older DOS-style functions. Note that 
in the Win32 API, CreateFileO is 
used to open existing files, as well as 
to create and open new ones. You 
can use the Win32 file I/O routines 
to open and read a file normally 
(synchronously), just as you would 
use fopenO and freadO under DOS or 
Windows 3.1, but you can also use 
the Win32 API to accomplish asyn¬ 
chronous file operations. 

The Win32 API provides three 
ways to perform asynchronous I/O. 
In all three cases, to perform asyn¬ 
chronous I/O, you have to pass the 
FILE_FLAG_0VERLAPPED flag to Create¬ 
FileO when you open the file. The 
other functions involved in these 
three methods are either ReadFileO 
and MriteFileO, or ReadFileExO and 
UriteFileExO. All four of these func¬ 
tions allow you to pass in a pointer 
to a structure of type OVERLAPPED, 
which is defined as shown in Figure 
1. 

All three methods have two com¬ 
ponents: how you start the asynchro¬ 
nous I/O, and how you detect that it 
has completed. For example, suppose 
you want to process one record 
while reading the next one into a 
buffer. After the first record is in 
memory, you would start an asyn¬ 
chronous read to fetch the second re¬ 
cord and then immediately start proc¬ 
essing the first record. After you fin¬ 
ish processing the first record, the 
read request to fetch the second record 
may or may not have completed, so 

(continued on page 28) 


Figure 1 Definition of OVERLAPPED structure 


typedef struct ..OVERLAPPED { 


DWORD Internal; 
DWORD Internal High; 
DWORD Offset; 

DWORD OffsetHigh; 
HANDLE hEvent; 

} OVERLAPPED; 


// reserved 
// reserved 

// file offset (low bytes) to start transfer 
// file offset (high bytes) to start transfer 
// event to signal when transfer is done 
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Asynchronous I/O: 
Behind the Scenes 

What's really happening behind the scenes 
when you start an asynchronous I/O operation on 
Windows NT? I will trace the progress of an asyn¬ 
chronous write request through the Windows NT 
operating system to a file on disk. 

Suppose your application has already success¬ 
fully opened a file for asynchronous I/O and has 
just called WriteFileO. WriteFileO calls into the 
Win32 environment subsystem (see Custer's Inside 
Windows NT for a description of environment sub¬ 
systems), which then calls the NtklriteFile I/O man¬ 
ager service. The I/O manager creates an IRP (inter¬ 
rupt request packet) for the request and passes it to 
the appropriate device driver. For simplicity, I'll treat 
the device driver as a single component. In reality, 
the IRP would first be passed to the appropriate file 
system device driver for the partition that the file 
resides on. The file system device driver in turn 
passes the IRP on to the driver for the physical de¬ 
vice. In the case of a SCSI hard disk, the device 
driver is further divided into class (applies to all de¬ 
vices of this type, such as a SCSI fixed disk), port 
(applies to all SCSI devices), and miniport (applies to 
the specific SCSI adapter controlling the SCSI device) 
driver components. 

The device driver puts the IRP in its own queue 
and returns status back to the Win32 subsystem. 
UriteFileO returns back to the application (GetLas- 
tErrorO will report a status of ERROR_IO_PENDING at 
this point). The application executes some code and 
then waits for the file handle, which it receives 
when the I/O operation is complete. When the de¬ 
vice driver processes the request from its queue, it 
determines the physical location on the disk and 
transfers the data to that location. When the trans¬ 
fer is done, the driver interrupts the system, trans¬ 
ferring control to the NT kernel. The kernel calls 
the ISR (interrupt service routine) registered for that 
driver/device. At this point, the driver is executing 
at a high 1RQL (interrupt request level), so it does 
only what it absolutely has to do and schedules a 
DPC (deferred procedure call) to handle the work it 
needs to do to finish processing the interrupt. 
When the DPC eventually interrupts the system, the 
kernel again gains control, but this time calls the 
driver's DPC routine. The DPC routine returns status 
information about the request that just completed 
back to the I/O manager. The I/O manager 
switches context to the calling application and cop¬ 
ies the status information (and the data, in the case 
of a read operation) to the caller's address space. 
Finally, it signals the file handle, releasing the appli¬ 
cation's waiting thread. □ 
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(continued from page 26) 

you need a way to say 'now I want to wait until this I/O 
request is complete.' Win32 offers a variety of methods 
for synchronizing; the sidebar ‘Win32 Synchronization Ob¬ 
jects' provides an overview. 

The first method for performing asynchronous I/O in¬ 
volves using ReadFileExO and UriteFileExO. In fact, you 
can only use these two routines asynchronously. In addi¬ 
tion to a pointer to an OVERLAPPED structure, these routines 
take a pointer to a callback routine - the I/O completion 
routine. When the file operation finishes, Windows calls 
the completion routine. The completion routine will not be 


called in a preemptive fashion though; after the I/O com¬ 
pletes, Windows waits until the calling thread is in an 
alertable state before calling your I/O completion routine. 
If you want the completion routine to be called once for 
each completed overlapped I/O operation, then you must 
call one of the alertable wait functions (HaitForSingleObjec- 
tEx(), WaitForMultipleObjectsExO, or SleepExO) from the 
thread that queued the overlapped I/O operation. The 
thread will sleep until an I/O operation completes and the 
completion routine is called. When there are no more 
queued operations, the wait function returns. You can 


Win32 Synchronization Objects 


When you take advantage of the power and flexi¬ 
bility of a fully preemptive, multithreaded operating 
system, one of the prices you pay is the complication 
of synchronization. Typical uses for synchronization in¬ 
clude protecting shared data and serializing operations 
that depend upon the completion of other operations. 
The Win32 API on Windows NT supports several dedi¬ 
cated synchronization objects (mutexes, semaphores, 
events, and critical sections), but other handles can 
also be used as synchronization objects (processes, 
threads, files, console, timers, and more). A synchroni¬ 
zation object is always in one of two states: signaled 
or not signaled. In general, threads waiting on objects 
are released when the object is signaled and are 
blocked when the object is not signaled. 

A mutex (from the phrase 'mutual exclusion') is like 
a single-lane bridge that only one thread at a time can 
cross. If one thread successfully acquires ownership of 
a specific mutex, then no other threads can own it un¬ 
til the first thread releases it. Mutexes can be used to 
protect a global resource from being accessed by mul¬ 
tiple threads at the same time. Note that a mutex (like 
a semaphore and an event) doesn't actually protect 
the resource directly; all threads wishing to access the 
resource must agree not to do so unless they have 
ownership of that particular mutex. Mutexes can be 
shared between processes. 

Semaphores are like variable-lane bridges that al¬ 
low a number of threads to cross at the same time. 
You specify how many threads can own the sema¬ 
phore when you initialize it. Once the maximum num¬ 
ber of threads have acquired ownership of a sema¬ 
phore, other threads trying to own it are denied own¬ 
ership until one of the owning threads releases it. 
Semaphores can be shared between processes. 

Events are more like public broadcasts or triggers. 
Events are often used when one thread wants to let 
another thread know that a specific event occurred. 
There are two kinds of events - manual-reset (once 
they become set, they must be explicitly reset) and 
auto-reset (they are automatically reset after being set). 
You can have multiple threads waiting on an event. 


When a manual-reset event is signaled, all waiting 
threads are notified, but when an auto-reset event is 
signaled, only one thread at a time is notified. Events 
can be shared by processes. 

Critical sections are similar to mutexes in that only 
one thread can own (enter) the critical section at a 
time. But critical sections can only be used to synchro¬ 
nize threads in one process. You can use several criti¬ 
cal sections in a single process, but a thread will exe¬ 
cute only if it is not in a critical section that has al¬ 
ready been entered by another thread. Although criti¬ 
cal sections are slightly more efficient (they have less 
overhead) than mutexes, they do not support time¬ 
outs for waiting. 

On a trivial level, you can use Win32's Interlocked- 
DecrementO, Inter!ockedlncrementO, and InterlockedEx- 
changeO to synchronize threads wishing to modify the 
same variable. In fact, if the variable is in shared mem¬ 
ory, you can even use this method to synchronize be¬ 
tween processes. 

There are three methods for sharing a semaphore, 
mutex, or event between processes. First, the proc¬ 
esses can agree upon a unique name and then open 
the synchronization object by name. Second, you can 
use DuplicateHandleO to create a copy of the handle 
for another process to use. Finally, if you enabled in¬ 
heritance for the object when it was created, child 
processes will inherit the object handle. 

Synchronization is a foreign concept to those who 
have programmed only on non-preemptive, non-reen¬ 
trant DOS-based PCs. When writing Win32-based code, 
it is important to always assume the worst - that all 
threads are running at the same time (which theoreti¬ 
cally could happen on a multi-processor system) and 
that a thread can be preempted between any two ma¬ 
chine instructions. The two most common pitfalls in 
using synchronization objects are deadlock conditions 
and race conditions. A deadlock condition occurs 
when threads end up waiting on each other indefi¬ 
nitely. If you avoid using infinite timeouts and always 
claim synchronization objects in the same order, you'll 
avoid many deadlock scenarios. A race condition oc- 
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name the completion routine anything you want, but it 
must have the following prototype: 

VOID CompletionRoutine(DWORD fdwError, DWORD dwTransferred, 
LPOVERLAPPED lpO); 

The second method uses ReadFileO and UriteFileO. 
One of the fields in the OVERLAPPED structure (see Figure 1) 
whose address you pass to these functions is an event 
handle (field hEvent). You can call CreateEventO to create a 
manual-reset event and then store its handle in the hEvent 


curs when you haven't synchronized events or 
threads properly. Then whether the program works 
or not comes down to the order the threads hap¬ 
pen to execute in. 

You can synchronize program execution by 
passing a synchronization object handle to one of 
the Win32 wait routines. All the wait routines (with 
the exception of SleepExO) accept as a parameter 
the object handle to be waited on. The object han¬ 
dle can be a handle of any synchronization object 
discussed above or any other waitable handle 
(which, as you'll see later, includes file handles). 
The wait routines differ based on how many condi¬ 
tions must be satisfied and whether it's an alertable 
wait. The UaitForSingleObjectO and UaitForSingleOb- 
jectExO routines wait for only one object handle to 
be signaled, but you can pass an array of up to 64 
object handles for the UaitForMultipleObjectsO and 
UaitForMultipleObjectsExO routines, in addition to 
waiting on object handles, the extended forms of 
the wait routines (UaitForSingleObjectExO and Uait¬ 
ForMultipleObjectsExO) can also be triggered by 
queuing an I/O completion routine for that thread. 
And, finally, you can use GetOverlappedResultO to 
wait on a synchronization object or just to check 
whether the object is signaled or not. GetOverlappe¬ 
dResultO calls UaitForSingleObjectO if the fUait flag 
is TRUE. 

What about using a simple variable as a syn¬ 
chronization flag? This violates the rule of assum¬ 
ing that execution can be preempted between any 
two instructions. The thread could be preempted 
after the flag is checked but just before it is set. 
The Windows NT scheduler treats operations to 
check and set Win32 synchronization objects as a 
single block of execution and will not preempt it in 
the middle. The Win32 synchronization objects are 
also much more efficient. Sitting in a loop waiting 
for a variable to change wastes precious clock cy¬ 
cles. When you use a wait function, the thread es¬ 
sentially goes to sleep (i.e., is not scheduled for 
execution) and does not consume CPU time. □ 
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Listing 1 asynch.h — Declaration of asynchronous 
I/O class 


/** . - ---- 

** ASYNCH.H : Simple Win32 File I/O Class Definition. 

** Environment: Windows NT, MS Visual C/C++ (32-bit) 

** ... **/ 

#ifndef _ASYNCH_H_ 

//define _ASYNCH_H_ 

//include <stdio.h> 

class CFilelO 

{ 

public: 

CFilelOtchar *pFilename, 

DWORD dwAccess = GENERIC_READ | GENERIC_WRITE, 

DWORD dwCreate = OPEN_ALWAYS, 

DWORD dwAttribute = FI LE_ATTRIBUTE_NORMAL, 

DWORD *dwStatus = NULL): 
virtual -CFilelOO; 

DWORD Read(BYTE *pBuffer. DWORD dwSize): 

DWORD Write(BYTE *pBuffer, DWORD dwSize); 

DWORD ReadWithAbandon(BYTE *pBuffer, DWORD dwSize); 

DWORD WriteWithAbandon(BYTE *pBuffer, DWORD dwSize); 

BOOL Close(void); 

BOOL Reopen(void): 

DWORD Seek(LONG 1 Offset, DWORD dwMethod = FILEJURRENT); 
HANDLE GetHandle(void); 

BOOL IOCompletetBOOL bWait = FALSE, DWORD ‘dwBytes = NULL); 
private: 

// copying/assignment not supported, so declare but 

// do not define 

CFi1elOCconst CFilelOA); 

const CFilelOA operator=(const CFilelOS); 


field of the OVERLAPPED structure. By passing a unique struc¬ 
ture and event handle for each I/O operation, you can 
overlap multiple read or write requests, and wait for one 
or more of them to complete by waiting on the corre¬ 
sponding manual-reset events. This method of overlapped 
I/O might be appropriate in a server process that uses a 
separate thread to handle each incoming client request. 

The final method for asynchronous I/O has the most 
limitations, but is also the easiest to implement and re¬ 
quires the least program redesign to take advantage of. 
Once again, you would use ReadFileO and UriteFileO to 
perform I/O, but instead of creating separate events for 
each I/O, you would just set the hEvent field in the OVER¬ 
LAPPED structure to NULL. This tells Win32 to signal the file 
handle when the I/O operation completes (you can wait 
for a file handle to be signaled, just as you can wait for 
an event). The limitation of this method (waiting on the 
file handle when you need to wait for the I/O to com¬ 
plete) is that you cannot start more than one overlapped 
I/O request; if you do, they will all signal the same file 
handle on completion and you will have no way to deter¬ 
mine which I/O completed. However, for many programs, 
overlapping a single read or write request at a time is a 
natural model, and an easy way to get the benefits of 
multithreading without much redesign work. 

Creating the CFilelO Class 

To demonstrate Win32's asynchronous file I/O capabili¬ 
ties, I wrote a very simple C++ class called CFilelO. The 
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declaration of CFilelO is in asynch.h (Listing 1) and the im¬ 
plementation is in asynch.cpp (Listing 2). This code uses the 
simple method of waiting on a file handle to synchronize 
execution, which is appropriate for situations where you 
don't need more than one outstanding I/O request per 
file. 

It's my personal programming style to stuff a lot of in¬ 
itialization work into the constructors of objects and thus 
avoid the requirement of an additional initialization or 
open method. If you prefer, this functionality could easily 
be pulled out and placed in an 'Open' member function. 
The CFilelO constructor takes the name of the file to open, 
a creation flag, and an attribute flag (these are the same 
flags that CreateFileO accepts). Since I can't return a status 
value from a constructor, I added a 
fifth parameter that I use to return 
status information back to the caller. 

Note that I also save the specified 
filename and attributes so that the 
file can be easily closed and re¬ 
opened. This might be useful if, for 
instance, you needed to occasionally 
close the file to let other processes or 
threads access it. 

The constructor initializes some 
fields in the OVERLAPPED olFile private 
data member. olFile must remain in 
scope while any overlapped I/O op¬ 
erations are in progress. To simplify 
the example, I always set the Off- 
setHigh field to zero. This limits the 
size of I/O operations to merely 32 
bits or 4 gigabytes - the NTFS file 
system uses 64-bit offsets allowing 
17 million terabyte transactions! I set 
the hEvent field to NULL because I use 
the file handle itself to synchronize 
all operations. In the destructor for 
CFilelO, I simply close the file handle 
if it is currently open. 

The CFileIO::Read() and 
CFilelO: :Urite() methods perform 
synchronous read and write opera¬ 
tions by calling ReadFileO and hlrite- 
FileO routines with a NULL for the 
OVERLAPPED structure. With no valid 
OVERLAPPED structure, the operation is 
performed synchronously, even if the 
file was opened with the 
FILE_FLAG_OVERLAPPED flag. But the op¬ 
posite is not true - you must specify 
FILEJLAGJOVERLAPPED when a file is 
opened in order to perform asyn¬ 
chronous I/O operations on that file. 

CFi lelO: :ReadUithAbandon() and 
CFilelO: :Uri teUi thAbandonl) routines 
perform asynchronous I/O opera¬ 
tions. I first check whether the file 
was opened with the FILE_FLAG_OVER- 
LAPPED flag. If it was not, then I simply 
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Listing 1 continued 


HANDLE hfile; 

BOOL bAsynch; 

OVERLAPPED olFile; 

char reopenName[MAX_PATH * 2]; 

DWORD reopenAccess, reopenCreate, reopenAttrib; 
DWORD dwPend; // place holder 

}; 

#endif 

/* End of File */ 
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perform a synchronous rather than 
an asynchronous operation. If every¬ 
thing is in order to perform asynchro¬ 
nous operations, I check whether an¬ 
other operation is already pending. 
Remember that one of the limitations 
of using the file handle as a synchro¬ 
nization object is that you cannot 
have multiple I/O operations queued 
at the same time to the same file 
handle. To verify whether any I/O 
operations for this file are still in pro¬ 
gress, I call CFileIO::IOComplete() (dis¬ 


cussed later) with TRUE as the first pa¬ 
rameter - indicating that I want to 
wait until any pending events com¬ 
plete. When CFilelO::IOComplete() re¬ 
turns, the dwBytes field contains the 
number of bytes transferred in the 
operation that just completed. This is 
crucial information, since ReadFileO 
and WriteFileO use the offset field of 
the OVERLAPPED structure as the current 
file position when operating asyn¬ 
chronously. So to keep the file 
pointer consistent, I increment the 


Table 1 Win32 file API comparison 

File Input/Output Routines 

CloseHandle 

Closes an open object handle 

close 

CreateFile 

Creates, opens or truncates a file’ 

creat,open,sopen 

DeviceloControl 

Send control directly to driver 

(none) 

DupiicateHandle 

Duplicates an object handle 

dup 

FilelOCompletionRoutine 

Called when asynch I/O completes 

(none) 

FIushFileBuffers 

Flushes buffered data to to disk 

commit 

LockFile,LockFi!eEx 

Locks a byte range in an open file* 

Jocking 

ReadFile,ReadFileEx 

Reads from a file* 

read 

SetEndOfFile 

Sets end-of-file to current position 

chsize 

SetFiiePointer 

Sets file-pointer position 

lseek,tell 

WriteFile,WriteFileEx 

Writes data to file* 

write 

UnlockFile,UnlockFileEx 

Unlocks a byte range in a file* 

Jocking 

File Management Routines 

CopyFile 

Copies existing file to new file 

(none) 

DeleteFile 

Deletes an existing file 

remove, unlink 

MoveFile,MoveFileEx 

Renames or copies a file 

rename,(none) 

Directory Routines 

CreateDirectory 

Creates a new directory 

mkdir 

GetCurrentDirectory 

Gets current directory for process 

getcwd,getdrive 

RemoveDirectory 

Removes an existing directory 

rmdir 

SetCurrentDirectory 

Changes the current directory 

chdir,ch drive 

File Searching and Change Notification Routines 

FindClose 

Close a find-file context 

(none) 

FindCloseChangeNotification 

Stop change notification 

(none) 

FindFirstChangeNotifi cation 

Setup change notification filter 

(none) 

FindFirstFile 

Finds the first matching file 

dos findfirst 

FindNextChangeNotifi cation 

Ask for notification of next change 

(none) 

FindNextFile 

Finds the next matching file 

dos findnext 

SearchPath 

Searches for a file 

_searchenv 
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Offset field by the number of bytes in 
the last transaction. 

I should point out that I've seen 
several documents, including Richter's 
Advanced Windows NT, state that the 
lpNumberOfBytesMritten and lpNumber- 
OfBytesRead parameters of MriteFileO 
and ReadFileO routines can be NULL 
when performing asynchronous file 
I/O. This certainly should be the case 
since the value is meaningless; the 
operation has most likely not com¬ 
pleted when MriteFileO or ReadFileO 
returns, so the system does not yet 
know how many bytes were actually 
transferred. However, specifying a 
NULL for the fourth parameter of 
MriteFileO and ReadFileO (even 
when performing asynchronous I/O) 
causes an Access Violation Exception! 


This may well be a bug in MriteFileO 
and ReadFileO, but for the time being 
you must pass a valid pointer, even 
though you can't use the result. 

CFileIO::Close() and CFilelO::Re¬ 
open () just provide a simple way to 
close and reopen the file without 
having to deallocate the object and 
reallocate it. In the case of 
CFilelO::Reopen(), no parameters are 
necessary since I automatically re¬ 
open the file with the parameters 
passed to the constructor. 

CFilelO::Seek() calls the Win32 
version of seekO, which is SetFile- 
PointerO. Once again I have limited 
the CFilelO class to 32-bit transaction 
lengths by always passing zero as 
the third parameter of SetFilePoin- 
ter(). The second parameter is the 


Table 1 continued 

File Information Routines 

GetDiskFreeSpace 

Returns amount of free disk space 

dos getdiskfree 

GetDriveType 

Returns type of specified drive 

(none) 

GetFileAttributes 

Returns file attributes 

_access 

GetFilelnformationByHandle 

Retrieves file information 

stat,fstat 

GetFileSecurity 

Get security of file object 

_access 

GetFileSize 

Returns size of specified file 

Jilelength 

GetFileType 

Returns type of specified file 

Jsatty 

GetFullPathName 

Retrieves a full path and filename 

Jullpath 

GetLogicalDrives 

Returns bitmask of valid drives 

(none) 

GetLogicalDriveStrings 

Returns strings for valid drives 

(none) 

GetVolumelnformation 

Returns file-system information 

(none) 

SetFileAttributes 

Sets file attributes 

chmod 

SetFileSecurity 

Set security of file object 

chmod 

SetHandleCount 

Set number of available file handles 

(none) 

SetVolumeLabel 

Sets a volume label 

(none) 

Temporary File Routines 

GetTempFileName 

Creates a temporary file name 

mktemp 

GetTempPath 

Returns path for temporary files 

(none) 

Note: For compatibility the following routines are still supported: _hread, _hwrite, 

Jdose, Jcreat, Jlseek, Jopen, Jread, Jwrite, GetDriveType, GetSystemDirectory, 
GetTempFileName, GetWindowsDirectory, OpenFile, and SetHandleCount. The following 
routine has been obsoleted: GetTempDrive. 

* In this case a file could be a normal disk-based file, pipe, communications resource, 
disk device, or console. 
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method type, which can be either FILE_BEGIN, FILE_CURRENT, 
or FILE_END depending on whether you want to seek from 
the beginning of the file, the current position in the file, or 
the end of the file. 


I provided a GetHandleO member function that returns 
the open file handle. This may be useful if you need to 
call a Win32 file routine other than the ones I supply via 
CFilelO member functions. 


Listing 2 asynch.cpp — Implementation of CFilelO class 


/** --- — .. 

** ASYNCH.CPP: Simple Win32 File I/O Class methods. 

“ Environment: Windows NT, MS Visual C/C++ (32-bit) 

** . . . - . -.**/ 

#include <windows.h> 

(►include "asynch.b" 

/**.....**/ 

CFilelO::CFileIO(char *pFilename, DWORD dwAccess, DWORD dwCreate, 
DWORD dwAttribute, DWORD *dwStatus) 

{ 

hFile = CreateFi1e(pFi1ename, dwAccess, 0, NULL, 
dwCreate, dwAttribute, NULL); 
if (hFile == INVALID_HANDLE_VALUE) *dwStatus = FALSE; 
else ‘dwStatus = TRUE; 

if (dwAttribute A FILE_FLAGOVERLAPPED) bAsynch = TRUE; 
else bAsynch = FALSE; 

strcpytreopenName, pFilename); 
reopenAccess = dwAccess; 
reopenCreate = dwCreate; 
reopenAttrib = dwAttribute; 

olFile.hEvent = NULL; 

olFile.Offset = olFile.OffsetHigh = 0; 

} // CFilelO 


IOComplete(TRl)E, idwBytes); 
olFile.Offset += dwBytes; 

return WriteFile(hF11e, pBuffer, dwSIze, AdwPend, &olFile); 
} // CFilelO::WriteWithAbandon 

/**..... — **/ 

BOOL CFilelO::Close(void) 

{ 

BOOL status = CloseHandle(hFile); 
hFile = NULL; 
return status: 

) // CFilelO::Close 

/** ... — . **/ 

BOOL CFilelO::Reopen(void) 

{ 

hFile = CreateFile(reopenName, reopenAccess, 0, NULL, 
reopenCreate, reopenAttrib, NULL); 
if (hFile == INVALID_HANDLE_VALUE) return FALSE; 
else return TRUE; 

} // CFilelO::Reopen 

/**. .**/ 

DWORD CFilelO::Seek(L0NG lOffset, DWORD dwMethod) 

{ 

return SetFilePointer(hFile, lOffset, 0, dwMethod); 

} // CFilelO::Seek 


/**.....**/ 

CFilelO: :-CFileI0() 

{ 

if (hFile != NULL) { 

CloseHandle(hFile); 
hFile = NULL; 

) 

} // CFilelO::-CFileI0 

/**----**/ 

DWORD CFileIO::Read(BYTE ‘pBuffer, DWORD dwSize) 

{ 

DWORD dwBytes; 

if (ReadFilelhFile, pBuffer, dwSize, AdwBytes. NULL)) 
return dwBytes; 
else return (DWORDJ0L; 

} // CFilelO::Read 

/**......**/ 

DWORD CFilelO::Write(BYTE ‘pBuffer, DWORD dwSize) 

{ 

DWORD dwBytes; 

if (WriteFile(hFile, pBuffer, dwSize, idwBytes, NULL)) 
return dwBytes; 
else return (DWORD)0L; 

) // CFilelO::Write 

/** ...*#/ 

DWORD CFilelO::ReadWithAbandon(BYTE ‘pBuffer, DWORD dwSize) 

{ 

DWORD dwBytes; 

// Sorry, you didn't open it for asynchronous operation, 
if (IbAsynch) return Read(pBuffer, dwSize); 

IOCompletefTRUE, SdwBytes); 
olFile.Offset += dwBytes; 

return ReadFilelhFile, pBuffer, dwSize, AdwPend, AolFile); 
} // CFilelO::ReadWithAbandon 

/**...**/ 

DWORD CFi1elO::WriteWithAbandon(BYTE ‘pBuffer, DWORD dwSize) 

{ 

DWORD dwBytes; 

// Sorry, you didn’t open it for asynchronous operation, 
if (IbAsynch) return Write(pBuffer, dwSize); 


/**. 

HANDLE CFilelO::GetHandle(void) 

{ 
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Listing 2 continued 


return hFIle: 

} // CFilelO::GetHandle 

/**.**/ 

BOOL CFilelO::I0Complete(B00L bWait. DWORD *dwBytes) 

{ 

// Don't wait for completion, just return current status 
if (!bWait) { 

if (!SetOverlappedResult(hFI1e, AolFile, dwBytes, FALSE) 

&A (GetLastErrorO = ERROR_IO_PENDING)) return FALSE; 
else return TRUE; 

} 

// Wait for the file I/O operation to complete 
else { 

If (GetOverlappedResultChFIle, SolFile, dwBytes, FALSE)) 
GetOverlappedResultChFile, SolFile, dwBytes, TRUE); 
return TRUE; 

} 

} // CFilelO:rlOComplete 
// End of File 


Listing 3 testmain.cpp — Asynchronous I/O 
demonstration program 


/**--- 

** TESTMAIN.CPP ; Demonstrates using CFilelO class. 

** Environment: Windows NT. MS Visual C/C++ (32-bit) 

**.....**/ 

include <windows.h> 

♦include <string.h> 

♦Include "asynch.h" 

♦define CHAR_FORMFEED 0x0c; // formfeed character 

♦define 8UF_SIZE 4896 // arbitrary buffer size 

/**.private prototypes--**/ 

BOOL FindNextSpoolFilename(char *); 

BOOL SynchronousFileCopytchar *, char *); 

BOOL AsynchronousFi1eCopy(char *. char *); 

/**-global variables and defines -.**/ 

char spoolPath[MAX_PATH]; 
char rootName[MAX_PATH]; 
char fsName[MAX_PATH]; 
char fi1eName[MAX_PATHT; 
char findFi1e[MAX_PATH]; 

/** ----- **/ 

VOID main(VOID) 

{ 

HANDLE hChange; 

DWORD dwWait, dwSPC, dwBPS, dwFC, dwTC; 

// first prompt user for spool directory 
printfC'Enter the print spool directory: \n"); 
gets(spoolPath); 

if (!SetCurrentDirectory(spool Path)) { 
CreateD1rectory(spoolPath, NULL); 

SetCurrentDirectory(spoolPath); 

) 

// show a little volume Information 
strcpyirootName. spool Path); 

rootName[3] = '\0'; // truncate to "x:\" 

GetVolumelnformationlrootName, NULL, 0, NULL, NULL, NULL, 
fsName, MAX_PATH); 

prlntfC'File system for volume %s is ls.\n", rootName, fsName); 
if (GetDiskFreeSpace(rootNaie. SdwSPC, AdwBPS, AdwFC, AdwTC)) 
printfCTotal free bytes; %d\n", dwFC * dwSPC * dwBPS); 

// form the search path, {spoolPathJW*.* 
sprlntflfindFile, "%s\\*,*", spoolPath); 

// monitor for create/deleted/renamed files in the spool dir 
if ((hChange = FindFirstChangeNotificationfspoolPath. FALSE, 
FILE_NOTIFY_CHANGE_FILE_NAME)) == INVALID_HANDLE_VALUE) 

ExitProcess(GetLastError()); 

// now wait (forever!) for notification of that event 
while (TRUE) { 

dwWait = WaitForSingleObject(hChange, INFINITE); 


CFilelO::IOComplete() lets you synchronize with the 
most recent asynchronous I/O request you made. If you 
pass FALSE to CFilelO::IOComplete(), it returns a TRUE or 
FALSE to indicate whether the pending operation has com¬ 
pleted - without waiting for a completion if there are any 
pending transactions. If a transaction is currently in pro¬ 
gress, then GetOverlappedResult() (passing the same file 
handle and overlapped structure that were used in the file 
I/O operation) wili return FALSE and GetLastErrorO will re¬ 
turn ERRORJOJENDING. If you pass TRUE to CFilelO::I0Com- 
pleteO, it will not return until the pending transaction has 
completed. 

To accomplish this, I first call GetOverl appedResul to with 
FALSE for the wait parameter, indicating I don't want to 
wait. This is important. If you call GetOverl appedResul t() 
with a value of TRUE for this parameter (indicating I want 
to wait) and there are no I/O operations in progress, then 
it will simply wait until another transaction starts and fin¬ 
ishes. For this reason, I first check if a transaction is in 
progress and then call GetOverl appedResul t() to wait for 
completion only if an event is in progress. If a transaction 
has finished, GetOverl appedResul t() returns the number of 
bytes actually transferred in the third parameter. I pass 
this on to the caller as the second parameter of the IOCom- 
plete method. 

Using the CFilelO Class 

I wanted to provide a simple yet useful program not 
only to demonstrate using the CFilelO class but also to 
show off a few more of the Win32 file API functions, so I 
wrote a console application that monitors a specified di¬ 
rectory. When a file is copied to that directory, the console 
application uses the CFilelO class to asynchronously copy 
that file to the printer. Essentially, it operates like network 
utilities that print any files that happen to appear in a 
predefined spool directory. 

The demonstration program is in testmain.cpp (Listing 
3). In mainO, I first query the user for the name of the 
spool file directory. If the directory does not already exist, 
I create it and select it as the current working directory for 
this process, using the Win32 functions CreateDirectory() 
and SetCurrentDirectoryO. Then, just for fun, I use 
GetVolumelnformationO and GetDiskFreeSpaceO to display 
what kind of file system is present on the drive containing 
the spool directory and how much disk space is available. 
Figure 2 shows shows the output asynch.exe generated 
when executing on my own PC. 

Next, I use the Win32 file change notification routines 
to monitor activity in the specified spool directory. What I 
am really interested in is file creation events in that direc¬ 
tory, but the finest granularity I can get with Win32's Find- 
FirstChangeNotificationO is notification of all file creations, 
deletions, and renames occurring in that directory (by 
specifying the FILEJ0TIFYJHANGEJ1LEJAME flag). FindFir- 
stChangeNotificationO sets up the notification filter and re¬ 
turns a change notification handle that can be used in 
subsequent calls to FindNextChangeNotification() or any of 
the Win32 wait routines. 
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Once the notification filter is initialized I go into an infi¬ 
nite loop waiting for a change notification (don't panic; 
you can simply type Ctrl-C when the DOS shell that is run¬ 
ning asynch.exe has the input focus or just close the DOS 
shell). The change notification handle is a waitable syn¬ 
chronization handle, so I can use UaitForSingleObjectO to 
wait for any changes matching the filter I specified when 
calling FindFirstChangeNotification(). When such a change 
occurs, I call my private FindNextSpool FilenameO routine. 
Unfortunately, the notification routines do not return any 
specific information about the file that was created/de¬ 
leted/renamed, so I used Win32's FindFirstFileO and 
FindNextFileO to search for any files in the spool directory. 

Notice that if several files appear at once in the spool 
directory, asynch.exe will spool them to the printer in the 
order in which they were located by the find routines 
(generally in alphabetical order). If files appear in the 
spool directory while I am printing a previous file, then 
the next time I call FindNextChangeNotificationO and Uait¬ 
ForSingleObjectO, I will be signaled immediately. But if 
anything should go wrong with that notification mecha¬ 
nism, I also have a backup plan - since I delete the file 
after I've finished printing, I will always get a second noti¬ 
fication and thus another opportunity to search the spool 
directory for files that need printing. An example of how 
this check is crucial is when asynch.exe first loads. If there 
are files already in the spool directory, it will catch those 
files the next time a new file is copied to the spool direc¬ 
tory. 


Listing 3 continued 


If (dwMait 1= UAITOBJECTJ) ExltProcess(GetLastErrorf)); 

// find the filename 
1f(FindNextSpoolFi1enameifi 1 eName)) { 

// copy the file asynchronously to the printer port 
AsynchronousFi 1 eCopyifi 1 eName, "pm"); 

// delete the file when done, triggers new search 
DeleteFile(fileName); 

) 

// now wait for the next event of this type 
if (FindNextChangeNotification(hChange) = FALSE) 
ExitProcess(GetlastError()); 

} //while 

FindCloseChangeNotification(hChange); 

} /* main */ 

/** ... - . -..**/ 

BOOL FindNextSpoolFi 1 enameCchar *fil eName) 

{ 

WIN32_FIND__DATA lpFind: 

HANDLE hSearch; 

BOOL status = TRUE; 

if ((hSearch = FindFirstFiletfindFile, &1 pFind)) 

== INVALID_HANDLE_VALUE) return FALSE; 

// if this is a hidden or system file, keep searching 
while (lpFind.dwFileAttributes 1= 32 &S status) 
status = FindNextFileihSearch, MpFind); 
FindClose(hSearch); 

if (lpFind.dwFileAttributes =» 32 4& status) { 

sprintf(fi1eName. "XsWfe", spool Path. lpFind.cFileName); 
printf("Spool 1ng file its to the printer.\n", fileName); 
return TRUE; 

} //if 
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Listing 3 continued 


return FALSE; 

} /* FindNextSpoolFilename */ 

/** __ **/ 

BOOL SynchronousFi 1 eCopyCchar *SourceName, char *DestName) 

{ 

unsigned long ulRead = 1, ulWritten = 1: 

BYTE formFeed = CHARJORMFEED; 

BYTE buffer[BUF_SIZE+l]; 

DWORD dwStatus; 

CFilelO SourcefSourceName, GENERIC.READ, OPEN_ALWAYS. 

FILE_ATTRIBUTE_NORMAL, AdwStatUS); 
if UdwStatus) return FALSE; 

CFilelO DestfDestName, GENERICJRITE, OPEN.EXISTING, 
FILE_ATTRIBUTE_NORMAL, JdwStatus); 
if UdwStatus) return FALSE; 

while (ulRead != 0) 

{ 

ulRead = Source.Read(buffer. BUF_SIZE); 
ulWritten = Dest.Write(buffer, ulRead); 

} 

//send form feed to printer 
Dest.Write!JformFeed, sizeof(CHAR)); 
return TRUE; 

} // SynchronousFi1eCopy 

/**.....**/ 

BOOL AsynchronousFi 1 eCopyCchar ‘SourceName. char *DestName) 

{ 

DWORD dwStatus=TRUE. dwRead=0, dwWritten=0, dwPend=0; 

BOOL bMore = FALSE; 

BYTE formFeed = CHAR_FORMFEED; 

BYTE bufl[BUF_$IZE+l], buf2[BUF_SIZE+l]. buf3[BUF_SIZE+l]: 

CFilelO Source!SourceName,GENERIC_READ, OPEN_ALWAYS. 

FILE_FLAG_OVERLAPPED, AdwStatus); 
if UdwStatus) return FALSE; 

CFilelO DestfOestName, GENERICJRITE, OPEN.EXISTING, 
FILE_FLAG_OVERLAPPED, AdwStatus); 
if UdwStatus) return FALSE; 

LPBYTE pRead » bufl; 

LPBYTE pWrite = buf2; 

LPBYTE pSwing = buf3; 

LPBYTE pTemp = bufl; 

// read the first buffer from the source file 
Source.ReadWithAbandontpRead, BUF_SIZE); 

while (IbMore) 

{ 

// wait for pending read from source file 
while ([Source.IOComplete(TRUE, JdwRead)); 

// swap buffer pointers 

pTemp = pRead; pRead * pSwing; pSwing = pTemp; 

// if more to read, start the next read from source file 
bMore = Source.ReadWithAbandon(pRead. BUF_$IZE); 

// wait for pending write to destination file 
while (!Dest.IOComplete(TRUE, idwWritten)): 

// swap buffer pointers 

pTemp = pWrite: pWrite = pSwing; pSwing « pTemp: 

// start the next write to parallel port 
Dest.WriteWithAbandontpWrite, dwRead); 

) //while 

//send form feed to printer, wait until it's done 
Dest.WriteWithAbandontJformFeed, 1): 
while UDest.IOCompletetTRUE, JdwWritten)); 
return TRUE; 

} // AsynchronousFileCopy 
// End of File 


I can use either SynchronousFi 1 eCopy 0 or Asynchronous - 
FileCopyO private routines to print the spooled file. Both 
routines use the CFilelO class. To make the test program 
more interesting, testmain.cpp always calls Asynchronous¬ 
Fi 1 eCopy (). AsynchronousFi 1 eCopy() is very general; you pass 
it two filenames and it copies the source file to the desti¬ 
nation file. In this case the source file is the filename ex¬ 
tracted from the spool directory and the destination file is 
the parallel printer port ( prn ). 

To get the most efficiency from asynchronous file I/O 
while at the same time not allowing more than one I/O 
operation to be simultaneously queued to any file handle, 
I use an extra buffer as a sort of swing buffer. I start the 
first priming asynchronous read (CFilelO::ReadUithAban- 
donO) and immediately wait for it to complete. Once the 
read has completed I assign the pSwing pointer to that 
buffer and use the pRead buffer to start another asynchro¬ 
nous read operation. If the last asynchronous write opera¬ 
tion (CFilelO::hlriteUithAbandon()) has completed, then I 
proceed to write the data pointed to by pSwing to the des¬ 
tination file. Then I wait for the last read operation to 
complete. I repeat this sequence until I get to the end of 
the source file. This way I am assuring that the source file 
is never waiting on the destination file or vice versa. Of 
course you must be extremely careful to avoid accessing a 
buffer (or worse yet, deallocating it!) until any pending I/O 
operations have completed. Also remember that you don't 
know how many bytes were actually transferred until the 
operation is completed. 

Building the ASYNCH10 Program 

I used the 32-bit edition of Microsoft Visual C++ 1.10 
to develop, debug, and build all the source code listed in 
this article. I simply created a new project named 
'ASYNCH' and specified a Project Type of 'Console appli¬ 
cation (.EXE).' The only files I added to the project were 
asynch.cpp and testmain.cpp. I used defaults for all other 
project options. As always, Visual C++ automatically cre¬ 
ated my makefile and all other necessary project files. The 
asynch.mak makefile and the asynch.exe executable are 
available on the code disk. If you're already familiar with 
the 16-bit version of Visual C++, then you'll be very much 
at home with the 32-bit version. There are a few new 
features, but all in all, it is very much the same develop¬ 
ment environment. It is definitely an improvement over 
the character-based tools provided with the Win32 SDK. 
The documentation indicates that it is a complete develop¬ 
ment environment and thus you no longer need the 
Win32 SDK at all. While this is probably true, I won't be 
purging the Win32 SDK from my hard disk until I have 
successfully rebuilt and tested all my Win32 modules - 
including my Win32 device drivers, which rely on the 
Win32 DDK (which relies on the Win32 SDK - you see 
my point!). 

Conclusion 

Although this little utility is functional, there are several 
obvious enhancements I could make. For instance, I could 
have designed the program to use separate threads for 


Page 38 — Windows/DOS Developer’s Journal 


March 1994 











the overlapped read and write operations - on a multi¬ 
processor system, I could literally be writing one buffer 
while I'm reading the next buffer. 

File locking is also a very powerful feature of the 
Win32 API. If there was a chance that another thread or 
process might need to access parts of the same file, I 
could open the file for sharing and then just protect the 
region I'm currently accessing by using Win32's LockFileO 
and UnlockFileO. 

And what about using the standard C run-time file rou¬ 
tines? Although they are supported, the run-time routines 
are typically mapped directly to one of the new Win32 
routines, so it's actually slightly faster to use the new rou¬ 
tines. But more important, don't mix the Win32 file rou¬ 
tines with the C run-time file routines. The file handles are 
not entirely interchangeable. 

Asynchronous file I/O can significantly increase per¬ 
formance since your program no longer has to wait for 
the mechanical movements of the disk drive and the file 
transaction to finally complete. Asynchronous file I/O also 
increases overall system efficiency - when a thread really 
does need to wait for a file transaction to complete, it just 
goes to sleep without consuming any real CPU time. The 
technique contained in CFilelO can give you an easy way 
to realize the benefits of multithreading for your application. 


Figure 2 Typical output from asynch.exe 


Enter the print spool directory: 
c:\spool 

File system for volume c:\ is FAT. 

Total free bytes: 13361152 

Spooling file c:\spool\AUTOEXEC.BAT to the printer. 

Spooling file c:\spool\CONFIG.SYS to the printer. 
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• Run multiple displays as one large virtual screen 

• View and execute multiple applications 

• Share data between screens by “click and drag” 

• FREE! Windows 3.X and OS/2 drivers 

• FREE! Technical support and BBS access 

• Price $995, MasterCard/VISA accepted 


Jw 

WIDEN YOUR VIEW 


To Order: 

404.455.3921 
Fax: 404.458.06l6 

Or Mail 

COLORGRAPHIC COMMUNICATIONS 

5388 New Peachtree Rd. 
Atlanta, GA 30341 
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Windows/DOS 

□ DEVELOPER'S JOURNAL 

New Products 

Industry-Related News & Announcements 


New Stacker Kit Includes Compression Engine 


Stac Electronics has released a new Stacker Devel¬ 
oper's Toolkit to give DOS and Windows programs ac¬ 
cess to Stacker data compression. The new version of 
the toolkit features 50 percent faster compression/de¬ 
compression engines, the ability to directly transfer com¬ 
pressed data from a Stacker drive to other storage media 
or computers, and enhanced code for detecting and us¬ 
ing Stacker hardware or software. Your code can use the 
toolkit to obtain the Stacker version number, and learn 
which drives in the system are compressed using 


Stacker. Unlike the previous version of the toolkit, this 
version's compression/decompression engines do not re¬ 
quire Stacker to be installed, but can take advantage of 
Stacker hardware or software when it is available. 

The Stacker Developer's Tool Kit v3.1 costs $295, in¬ 
cludes a full copy of Stacker v3.1 for Windows and DOS, 
and is available directly from Stac at (800) 522-STAC. A 
technical specification of the toolkit functions is available 
from StaCs BBS at (619) 431-5956, CompuServe (CO 
STAC), and America Online (keyword STAC). 


Omega Systems Offers $99 Windows Version Control 


Omega Systems has released VERSIONS, a new ver¬ 
sion control system for Windows. VERSIONS uses a meth¬ 
odology based on project milestones, similar to the log 
files used in mainframe databases. Projects are broken 
down into milestones, with multiple interim versions be¬ 
tween milestones. Once a project reaches a milestone, 
you can use VERSIONS to safely discard all previous ver¬ 
sions and archive the milestone version. The product sup¬ 
ports multi-user network, user-definable maximum 
number of versions per file, file descriptions and check-in 


comments, suggestions on which files need to be 
checked in or out, customizable project-wide reporting, 
temporary versus permanent versions, connection to Mi¬ 
crosoft Mail for Windows, and inter-project file delete, re¬ 
name, copy, and move. 

VERSIONS costs $99; networked installations require 
one copy per workstation, but site licenses are available. 
For more information, contact Omega Systems, 18872 
MacArthur Blvd., Ste 400, Irvine, CA 92715, 

(714) 253-6700; FAX (714) 253-6712; CIS: 73531,137. 


XDE Provides xBase Windows Development 


XDE is a new integrated set of components for devel¬ 
oping custom Windows applications using object-ori¬ 
ented techniques. The package includes a language, 
Express Development Language (XDL), a 4CL that ex¬ 
tends XBase with built-in object classes for GUI develop¬ 
ment. XDL gives you access to both dBase compatible 
databases and standard Windows controls. The com¬ 


pany plans to offer a built-in object for Visual Basic cus¬ 
tom controls and additional add-on object classes. 

XDE costs $695 and includes a 90-day, money-back 
guarantee. For more information, contact Micro Design 
International, Inc, 6985 University Boulevard, Winter 
Park, FL 32792-6173, (407) 677-8333; 

FAX (407) 677-8365. 


Multi-Doc Provides Multi-format Help Generation 


DAB1WA Ltd. is shipping Multi-Doc, a new tool for 
generating online help. Multi-Doc can generate output in 
a variety of formats (Windows help file, Expert Help, Nor¬ 
ton Guides, MS QuickHelp, FoxDoc, Word for Windows, 
and generic ASCII) from a single document. Multi-Doc 
can also convert existing Windows or DOS-based docu¬ 
mentation, help files, and manuals from one format to 


another, with complete control over the formatting for 
each type of file. 

Multi-Doc costs $199 and is royalty-free. For more in¬ 
formation, contact DABIWA Ltd., 301 Joseph Drive, West 
Chester, PA 19380, (800) 533-3183 or (215) 692-8130; 
FAX (215) 692-8172. 


(continued on page 60) 
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Windows Multimedia: Part 2 
Spiral Bitmap Special Effects 

Charles Mirho 



Borland C++ v3.1 
Symantec C++ v6.0 
Microsoft C/C++ v8.0 


One way to enhance the visual aspect of your application is to draw bit¬ 
maps with algorithms that imply movement, rather than just plopping them on 
the screen with a single call to BitBltO. Last month, I provided algorithms for 
drawing bitmaps toward the center from the top and bottom, left and right, 
and diagonally. This month, I will show you how to draw them in a spiral, from 
the outside in or the inside out. 

Before displaying a bitmap, you must first load it into memory somehow, by 
loading a resource or reading a file, for example. The code disk (see the table 
of contents for availability) contains a complete demonstration program that 
can load a bitmap from a file and display it using the special effects described 
in this article. 

The Spiral Algorithm 

A spiral effect involves displaying the bitmap from the outer sides toward 
the center, or vice versa, one small block at a time. I arbitrarily chose to use a 
four-by-four block of pixels in my code. You could use a larger or smaller 
block, depending upon how you want the effect to look. 

For an inward spiral, in which the outer sides spiral toward the center, I 
display the blocks in the sequence shown in Figure 1 until they meet in the 
middle. The C code for the spiral effects is in Figure 2. Notice that since the 
pixel block is square, I specify both BitBltO dimensions with the constant 
BLOCK. BLOCK is defined as 4 pixels, for a total block size of 16 pixels. In the 
inward spiral, a master while loop keeps the algorithm running until either the 
left and right edges run together, or the top and bottom edges run together. In 
either case, the entire bitmap has been displayed. 

Within the while loop are four simple for loops, each responsible for display¬ 
ing an edge of the rectangular bitmap. The first for loop displays the top edge 
of the spiral. 

/* top edge */ 

for (x=left;x<=right;x+=BL0CK) 

BitBlt(hDC, x, top, BLOCK. BLOCK, hMemDC, x, top, SRCCOPY); 
top += BLOCK; 


Charles Mirho is a consultant specializing in Multimedia and Telephony. He holds a 
Master's degree in Computer Engineering from Rutgers University. He can be reached 
on CompuServe at: 70563,2671. 
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Figure 1 Drawing a bitmap in an inward spiral 
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The loop variable x represents the current x-coordinate of 
the block to display. This variable is initialized to the left 
edge of the display surface, which is coordinate 0 in the 
default coordinate system. The value of the y-coordinate 
for the top edge is fixed at top. Initially, top is set to 0, 


which is the top edge of the display surface in the default 
coordinate system. The for loop moves across the top 
edge by incrementing x a block at a time. When it reaches 
the right edge, the loop ends, and the top edge coordi¬ 
nate is incremented by BLOCK units. The next time the loop 
executes, the top edge will be one block below where it 
was the last time, converging on the center. 

The second for loop takes care of displaying the right 
edge of the spiral. 

/* right edge */ 

for (y=top;y<=bot;y+=BLOCK) 

BitBltfhDC, right, y, BLOCK, BLOCK, 
hMemDC, right, y. SRCCOPV); 
right -= BLOCK; 

The loop variable y represents the current y-coordinate of 
the block to display. This variable is initialized to the right 
edge of the display surface, which is the width of the bit¬ 
map minus BLOCK units. Why subtract BLOCK units? Because 
BitBltO uses the upper left corner of the block as the 
origin point when displaying the block. So, BitBlt()\ng a 
square BLOCK pixels wide by BLOCK pixels deep at point (x,j) 
will move bits from within the coordinates (x+BLOCK, 
y+BLOCK). Thus, the last valid x coordinate for a block 
within the bitmap is 

bitinfo->bmiHeader.biWidth-BLOCK 


WOW! Now a Windows Version!!! 

No Source? No Problem, 


Tf I hat would you do if you 
11/ couldn't find the source to the 
” program you needed to 
change? Sure you could start from 
scratch at great time and expense, but 
why not get the source from the 
program itself with DisDoc™, the 
most powerful reverse engineering 
editor available! 


"GREAT! This is the disassembler I’ve 
dreamed about." 

M.E.W. Patterson, CA 


Programmers who used to shy away 
from fixing outmoded programs with 
no source code are going to discover 
a valuable new talent: the ability to 
modify and revise code that would 
cost way too much to start over (it's a 
programming manager's dream). 



Imagine converting an object library 
into a source library, enhancing a 
sourceless program your boss 
thought was set in concrete, 
getting a head start on 
programming for a hardware 
device by looking at the 
vendor's own software driver. 

Why wait for your current 
disassembler to go to Win¬ 
dows? We will upgrade 
anyone with a DOS dis¬ 
assembler to DisDoc for 
Windows™ for just $99! 

To order DisDoc™ for DOS or 
Windows call now: 

1-800-336-1961 

1-203-489-5335 voice 1-203-489-5746 fax 
free demo on BBS (203) 953-6196 


(DOS Version) 



(Windows Version) 

or send check or money order for: 

DisDoc for Dos $249.95 
DisDoc for Windows $249.95 
Both $349.95 

plus $6 for s&h, $10 overseas 
(CT residents add 6% tax) 


RJSwantek, Inc. • 33 Spencer Brook Road • New Hartford, CT 06057 USA 


MasterCard & Visa • Shipped Immediately Via UPS Blue inside USA 
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the width of the bitmap minus BLOCK. The last valid y coor¬ 
dinate is 

bitinfo->bmiHeader.biHeight-BLOCK 

the height of the bitmap minus BLOCK 

The next two loops repeat this process for the bottom 
and left edges. The only difference is that the bottom- 
edge loop scans backwards across the display surface, 
moving right to left, and the left-edge loop scans up the 
display surface from bottom to top. 

If the bitmap is not a multiple of BLOCK pixels in either 
dimension, then complexities arise on the final iteration of 
the algorithm. To handle this situ¬ 
ation, it is necessary to adjust the 
size of the block on the final iteration 


Figure 2 Code to implement spiral bitmap display 


int bnpSpiral (HDC hDC, int effect) 

{ 

int left=0, top=0. right=(int)p_binfo->bmiHeader.biWidth-BLOCK. 

bot=(int)p_binfo->bmiHeader.biHeight-BLOCK; 
int width = (int)p_binfo->bmiHeader.biWidth-BLOCK. 

height = (i nt)p_binfo->bmiHeader.biHeight-BLOCK; 
int x, y; 

DWORD nextTime = GetTickCountO + 50; 

SetDIBits(h_memDC, h_bmp, 0, 

(W0RD)p_binfo->bmiHeader.biHeight, hp_bits, 
p_binfo, DIB_PAL_C010R$): 


to account for any stray bits. 

Outward Spiral 

An outward spiral effect is a bit 
trickier than an inward spiral. This 
outward spiral effect is sometimes 
called an explode, because the bit¬ 
map appears to explode outward 
from the center. Not surprisingly, the 
algorithm for this effect resembles 
the algorithm for the inward spiral, 
with some of the operations inverted. 
Instead of starting at the edges of the 
bitmap and stopping at the center, I 
start displaying from the center and 
stop when I reach the edges. This 
changes the master loop condition 
and the initial edge values. Instead of 
incrementing or decrementing the 
edge positions after each for loop, I 
increment or decrement before each 
for loop. I also have to check more 
carefully when 1 reach an edge. Oth¬ 
erwise the algorithms are identical. 

Notice the initial conditions for the 
edge variables in Figure 2. The initial 
value of the left edge is 

int left = width/2 - (width/2) % BLOCK; 

where width is the width of the bit¬ 
map adjusted down by one block 
size. The left edge is initialized to the 
nearest block boundary left of the 
center. For example, if the bitmap is 
56 pixels wide, then the initial left 
edge value is 

width = 56-BLOCK = 52 
width/2 = 52/2 = 26 
(26)%BL0CK = 2 (BLOCK = 4) 
left = 26 - (26)%4 = 24 



for C/C++ 

presents Bug # 1733 


#include <stdio.h> 

class X 
{ 

public: 

int *px; 

X( int init ) 

{ px = new int; *px = init; } 
~X() { delete px; > 

); 

void print( X x ) 

{ printf( "%d\n", *x.px ); } 

int main() { 

X x(15); print( x ); 

X y(16); print( x ); print( y ); 
return 0; 

} 


The output the programmer expected to see was 15,15, and 16. Instead, he got 
15,16, and 16. What went wrong? Call if you need a hint. Refer to Bug #1733. 


PC-lint for C/C++ will catch this and many 
other bugs. It will analyze a mixed suite of C 
and C++ modules to uncover bugs, glitches, 
quirks and inconsistencies. 

Numerous C++Warnings and Messages: 
Are your inherited destructors virtual? Are 
your constructor new's matched by your 
destructor delete's? Are your initializers 
in order? Are names inadvertently hiding 
other names? Are your C++ modules 
consistent with your C modules? Much, 
much, more. 

Plus Our Traditional C Warnings: 

Uninitialized variables, unaccessed variables, 
possibly uninitialized variables, strong type 
mismatches, indentation irregularities, loss of 
precision, strange uses of Booleans, 
signed/unsigned mismatches, suspicious 
expressions, unused macros, etc. etc. 


Full C++ Support - PC-lint for C/C++ 
is based on the ARM and is tracking the 
latest ANSI/ISO draft including exceptions 
and templates. It supports both Borland and 
Microsoft C/C++. 

Options Galore: A plethora of options for 
message suppression, message format, 
compiler dependencies, etc. All messages 
can be individually suppressed or enabled, 
both locally and globally. Numerous 
compilers/ libraries supported. Runs on 
MS-DOS (Optional built-in 386 DOS 
extender) and OS/2. 

PC-lint for C $139 
PC-lint for C/C++ $239 

PC-lint users: call for update pricing 
Unix and Mainframe programmers: 

call for pricing for FlexeLint. 



3207 Hogarth Lane, Collegeville, PA 19426 

CALL TODAY (215)584-4261 Or FAX (215)584-4266 

30 Day Money-back Guarantee. 

PA add 6% sales tax. PC-lint and FlexeLint are trademarks of Gimpel Software 
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The initial x coordinate is two pixels left of center. The 
initial value for the top edge is computed the same way 
based upon the height of the bitmap, so that the initial 
top is always slightly above center. By aligning on a block 
boundary this way, I ensure that the algorithm terminates 
exactly on the outer edges of the bitmap, without any 
stray bits. These initial values also ensure that the algo¬ 
rithm will reach the left and top edges before it reaches 
the right and bottom edges, respectively. Work through 


the numbers for a few different bitmap dimensions and 
you will see that this is so. Thus the master loop condition 
becomes 

while (bot < height || right < width) 

The OR condition is necessary because, depending on the 
ratio of width to height, either the bottom or the right 
edge will be the last to complete. Within the master loop I 


Figure 2 continued 




if (effect == IDM INWARDSPIRAL) { 

left, y, SRCCOPY); 

while (left < right && top < bot) { 

left += BLOCK; 

/* top edge */ 

for (x=left;x<=right;x+=BL0CK) 

while (GetTickCountO < nextTime) 

BitBlt(hDC. x, top, BLOCK, BLOCK, h memDC, 

; 

x. top, SRCCOPY); 

nextTime += 50; 

top += BLOCK; 

/* right edge */ 

} //end while (not at center) 

for (y=top;y<=bot;y+=BLOCK) 

} /* end if (inward spiral */ 

BitBltthDC, right, y, BLOCK, BLOCK, h memDC, 


right, y, SRCCOPY); 

if (effect == IDM OUTWARDSPIRAL) { 

right -= BLOCK; 

left = width/2 - (width/2) % BLOCK; 

/* bottom edge */ 

right = left; 

for (x=right;x>=left;x-=BL0CK) 

top = height/2 - (height/2) l BLOCK; 

BitBltthDC. x, bot, BLOCK, BLOCK, h memDC, 

bot = top; 

x, bot, SRCCOPY); 

/* initial block */ 

bot -= BLOCK; 

BitBltthDC, left, top. BLOCK, BLOCK, h memDC, left, 

/* left edge */ 

top. SRCCOPY); 

for (y=bot;y>=top;y-=BL0CK) 

while (bot < height II right < width) { 

BitBltthDC. left, y, BLOCK, BLOCK. h_memDC, 

/* top edge */ 
if (top > 0) { 


top -= BLOCK; 

for (x=left;x<=right;x+=BL0CK) 


BitBltthDC, x, top, BLOCK, BLOCK, 


h memDC, x, top, SRCCOPY); 

PINNACLE 

} /* end if (more to go on top edge) */ 

/* right edge */ 
if (right < width) { 


right += BLOCK; 

RELATIONAL 

for (y=top;y<=bot;y+=BL0CK) 

BitBltthDC, right, y. BLOCK. BLOCK, 

hjnemDC, right, y, SRCCOPY); 

ENGINE 

} /* end if (more to go on right edge) */ 

/* bottom edge */ 
if (bot < height) { 


bot += BLOCK; 

for (x=right;x>=left;x-=BLOCK) 

The Portable Compact Client-Server RDBMS 

BitBltthDC, x. bot. BLOCK, BLOCK, 

For C/C++ Programmers 

h_memDC, x, bot, SRCCOPY); 

} /* end if (more to go on bottom edge) */ 

DOS, Windows, UNIX, Mac, OS/2, NT, VMS 

/* left edge */ 
if (left >0) { 


left -= BLOCK; 

for (y=bot;y>=top;y-=BLOCK) 

Painless Database Proarammina! 

BitBltthDC. left, y, BLOCK, BLOCK, 

h memDC, left, y. SRCCOPY); 


} /* end if (more to go on left edge) */ 

■\7ermont 

✓X Database 

while (GetTickCountO < nextTime) 

nextTime += 60; 

} //end while (not done spiral out) 

} /* end if (outward spiral */ 

Corporation 

JL 


return 0; 

1-800-822-4437 

} /* end function (bmpSpiral) */ 

Vermont Database Corporation / 400 Upper Hollow Hill Road 

/* End of File */ 

Stowe, VT 05672 USA 


802-253-4437 / 802-253-4146 (FAX) 



□ Request 213 on Reader Service Card □ 
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C CODE FOR THE PC 

source code, of course 

Graphic 7.0 (high-resolution, scientific plots in color & hardcopy, contour plots, device independence).$370 

X/DOS and Xt/DOS (Xlib with X client and Xt toolkit for DOS; port X code to DOS; Xt/DOS r equ ires X/DOS and 32-bit compiler) . . each $300 
ZIP Image Processor & Victor Image Library Version 2.2 (brightness, contrast, merge images, TIFF/GIF/PCX/bin, HP ScanJet support) . . $290 

The Snooper (Ethernet protocol analyzer for Novell Net mre and LAN Manager Networks; capture packets; real-time display).$275 

Embedded BIOS (full-featured, real-time input/output system; PC, XT^ AT; for example, 80186 with 8259 interrupt controller).$260 

C/C+ + libraries by Code Farms (persistent C structures, ER models, dynamic arrays, database functions, Jolt Award winner, specify C or C++)$250 

TbrboTgX (Release 3.0; HP, PS, dot drivers; CM fonts; LaT+X; MetaFont).$250 

Rogue Wave tools.h++ or math.h-|-+ Class Library (extensive docs).each $240 

NE W! Crusher! (platform-independent data compression for network transfer; beats PK & LH on binary; directory trees; portable C) .$215 

COMM-DRV (complete interrupt-driven serial communication libraries & device drivers; full source).$155 

TE Editor Developer’s Kit Ver. 3.0 (full screen editor, undo command, multiple windows; with Word Processing $230).$155 

Minix Operating System (Version 1.5; Unix-like operating system, includes manual; specify 5.25” or 3.5” diskettes).$150 

NEW! XASM (cross assemblers & utility programs; 65xx, 68xx, 80xx; Intel or Motorola hex format; macro preprocessor) .$150 

Delorie GCC for MS-DOS (Version 222; includes C+ +, assembler, DOS extender, 387 emulation; complete source oode and makefiles) . . $150 

Updated! Moby Crypto (PGP, DES, Secure Hash, UFC, MDs, Crack 4.1, Lucifer, IDEA, VCR+, large integer packs, tutorials, more; not for export) . . $150 

Lisp for DOS (Kyoto Common Lisp and CLISP; KCL includes Lisp-to-C translator for building mixed Lisp/C programs) .$140 

Ibrow (Version 4.1; programmer’s Windows-based editor, large files, help, undo/redo, drag-n-drop, function & type tags).$135 

Booter Tbolkit (floppy disk bootstrap routines, DOS file system, light-weight multitasking, windows, fast memory management) .$120 

Updated! SCM (portable Scheme in C, IEEE standard, includes JACAL symbolic math package; SCM-4D0/SLIB-1D5/JACAHA3) .$100 

PC/IP (CMU/MIT TCP/IP for PCs; Ctynwr drivers, NFS server, Bdale mailer, PCRoute/PCBridge, NDIS/ODI drivers, Beholder, more) . . . $100 

DA (disassembler for Microsoft’s New Executable (NE) binary files including Windows .exe, .drv, .dll, and .fit).$95 

Script Interpreter (a command script interpreter for DOS-based systems; C-like script language; lots of features).$90 

CELP 3.2c (Federal Standard 1016 Code Excited Linear Predictive voice sampling and encoding; voice over 4.8kbps; Unix code).$80 

CPPCOMM (C+ + serial communications class library for DOS, Windows, OS/2 and NT; includes X/Y/Zmodem).$75 

ET Neural Net (back error propagation and Kohonen; specify DOS text, DOS VGS, or Windows).$75 

FlexList (doubly-linked lists of arbitrary data with multiple access methods; specify C or C++).$65 

Kier DateLib (all kinds of date manipulation; translation, validation, formatting, & arithmetic).$60 

Coder’s Prolog (Version 3.0; inference engine for use with C programs).$60 

Updated! PCCTS Version 1.10 (Purdue Compiler Construction Tool Set; like YACC and LEX together with lots of additional features).$60 

Container Lite V 1.82 (C+ + & FLC wrapper emulators; portable, persistent containers of arbitrary data including pointers).$50 

BigFloat (arbitrary precision floating point arithmetic and functions; includes BCD conversion).$50 

EZCalc (ASCII algebraic expression evaluator, unlimited parenthesis nesting, symbols, 32 built-in functions, easily extended).$50 

Backup & Restore Utility by Blake McBride (multiple volumes, file compression & encryption).$50 

CLIPS Version 6.0 (rule-based expert system generator, Windows compatible; hardcopy manuals additional) .$50 

SuperGrep (exceptionally fast, revolutionary text searching algorithm; also searches sub-directories).$50 

OBJASM (convert .obj files to .asm files; output is MASM compatible) .$50 

Editor Pack (20 public domain editors; micromacs 3.12, Stevie, Elvis, Moke, mg2a, DTE, Jove, Origami, CE & GRIEF).$50 

Exceptions for C (Ada-like exception handling for C programs; exceptions for any block; exceptions can be reraised).$45 

DES Encryption & Decryption (2500 bits/second on 4.77MHz PC for on-the-fly encryption at 2400 baud; not for export).$40 

Database Pack (9 databases - simple to complex: isam, bplus, AVL, SDB, ID, gdbm, Requiem, Ingres89, Postgres).$35 

COP (poor man’s C++; C macro package which implements C++in C) .$35 

NEW! OCT (Object C Translator, essentially Brad Cox’s Objective-C Version 4) $35 

RXC & EGREP Version 20 (Regular Expression Compiler and Pattern Matching; finite state machine from regular expression).$35 

Bison & BYACC (YACC workalike parser generators; documentation; includes Cand C++ grammars) .$35 

Spell Pack (6 spelling programs, a hyphenator, 2 utility packs and a 60K word list: Ispell, Microsp, Sp, Cspella, Spell, Dawg, Soundex) .... $30 

REGX Plus (Version 3.0, search and replace string manipulation routines based on compiled regular expressions).$30 

GNU Awk & Diff for PC (both programs in one package).$30 

Big Number Pack (7 arbitrary precision arithmetic packages in C, one in Fortran but free Fortran-to-C converter is included) .$30 

Crunch Pack (30 file compression & expansion programs; now includes portable ZIP).$30 

NE W! OORT (C+ + ray tracing code from the book by Nicholas Wilt) .$30 

OEmacs (full GNU Emacs for DOS and Windows DOS box; C+ + support, etags++, lots of .el files) .$25 

NEW! CTask Version 2.22d (robust MS-DOS multitasking kernel; C functions run as light-weight processes; mailboxes, interrupts, pipes, etc.) . . . $25 

PERL for MS-DOS (Version 4.019; C, sed, awk, and shell all rolled into one language; includes hardcopy docs).$25 

Updated! FLEX Version 2.4.3 (fast lexical analyzer generator; new, improved LEX).$25 

GNU RCS (FSFs version of the Revision Control System; like Unix’s SCCS only better, keeps track of software development).$20 

Data 

Moby Thesaurus II (6,000 root words, 2.5M synonyms, ’’common sense”, concept related searches) .$500 

Moby Pronunriator II (175,000 words & phrases encoded with full IPA pronunciation & emphasis points).$265 

Moby Part-of-Speech II (230,000 words and phrases described by prioritized part(s)-of-speech).$170 

Moby Hyphenator II (185,000 words fully hyphenated/syllabified).$105 

Moby Words II (610,000 words & phrases with Scrabble(tm) word list, place names, baby names, acronyms, core list for spell checkers) . . . $100 

U. S. Cities (names & longitude/latitude of 32000 U.S. cities and 6,000 state boundary points).$35 

The World Digitized (100,000 longitude/latitude of world country boundaries).$30 

CD-ROMs 

BSD/386 (POSIX-compatible O/S; complete development package, full networking, kernel debugger, X11R5, DOS box; complete source code) $900 

NE W! AI CD-ROM (expert systems, neural networks, genetic algorithms, fuzzy logic, linguistics/naturallanguage).$105 

FontMaster II CD Library (soft fonts for HP and HP compatible laser printers, 36 different type faces; 5,200 bit mapped fonts; 300MB) . . . $70 

Updated! Prime Time for Unix (Volume 3, No. 1, January, 1994; over 6GB of Unix C code).$60 

Walnut Creek Libris Britannia (over 60OMB of the best of British boards; not all source included).$55 

NEW! Mailer’s Lookup (9-digit ZIP codes by street address or company name, distances between ZIP codes, phone locations; on-line tool) .... $50 

Linux/GNU/X by Yggdrasil Computing (1st production release; run from the CD; TCP/IP & NFS; drivers; MPEG; SCSI support; lots more) . $45 

Walnut Creek C User’s Group (Volumes 100 to 364).$40 

NE W! Walnut Creek Linux VO.99.13 (100’s of tools; drivers for all sound, CDs, video; X-Windows; software engineering tools; easy install.$40 

InfoMagic Unix (three public domain Unix systems: 386BSD (version 0.1), Linux (version 0.99.10), and NetBSD).$40 
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check that the algorithm has not 
reached the limit of each edge before 
displaying the edge, because, again, 
the edges may complete in different 


orders, depending on the dimensions 
of the bitmap. Using these initial val¬ 
ues creates one small problem: it 
leaves a BLOCK -sized hole in the cen¬ 
ter where no bits are displayed. Fig¬ 
ure 3 shows how this arises in the 
early stages of the algorithm. To fix 
this problem, I do an initial BitBltO 
before the master loop to fill in the 
hole left by the outward spiral algo¬ 
rithm. 

Timing 

On faster machines, the spiral ef¬ 
fect may lose some punch because it 
executes so quickly. To slow things 
down, I put a delay loop at the end 
of the master while loop. In Figure 2, 
I use a 10ms delay: 

DWORD nextTime = GetTickCountO + 10; 
while (left < right && top < bot){ 


while (GetTickCountO < nextTime) 
nextTime += 10; 

} /* end while (not at center) */ 


Conclusion 

The spiral, like most bitmap ef¬ 
fects, is built algorithmically from 
many BitBltOs of small blocks. Sev¬ 
eral assumptions helped simplify the 
implementation. First, I assumed the 
default Windows coordinate system 
with x increasing right and y increas¬ 
ing down. Other coordinate systems, 
particularly those involving coordi¬ 
nates of mixed sign, can complicate 
the algorithms considerably. Also, I 
did not address the complexities of 
handling bitmaps which are not a 
multiple of the block size, although 
this case is relatively simple to deal 
with. You may also have noticed that 
the inward spiral algorithm is slightly 
inefficient because each edge loop 
overlaps one block with the edge 
loop immediately preceding it. The 
performance hit from this flaw is 
probably insignificant. □ 
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C++ Member Function Callbacks 
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What is the purpose of a callback function? Typically, it is used when a 
generic function needs to allow programmers some flexibility in specifying a 
generic action. A good example is the ANSI C function qsortO. This function 
sorts generic objects via the quicksort algorithm. In order to allow the program¬ 
mer to sort any type of object in any order, qsortO takes a callback function. It 
is the job of this callback to determine what type of data is being manipulated 
and in what order the data should be sorted. Windows makes extensive use of 
callback functions, principally for window messages, but also for such functions 
as SetTimerO and EnumUindowsO. 

Windows C programmers are accustomed to creating window callback pro¬ 
cedures to define the behavior of the windows in their applications. When they 
move to C++, it is only natural for them to want to place callback procedures 
in C++ classes. Unfortunately, that is easier said than done, since C++ class 
member functions are not quite the same as ordinary C functions. 


Craig Arnush is a software engineer at OCTuS, Inc. in San Diego, CA. He's also a mem¬ 
ber of Team Borland on CompuServe. He is currently co-authorig a book entitled 
Teach Yourself Borland C++ v4.0 in 21 Days. Craig can be reached via the Internet 
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Member Versus Non-Member Functions 

Regular global functions in C++ are similar to ordinary 
C functions. You can use global C++ functions as callback 
procedures, just as you would in C. Member functions, on 
the other hand, are declared in a C++ class. They have 
access to all other functions and data declared anywhere 
in the class definition, except for any data that might be 
local to one of the other member functions. 

There are two different kinds of member functions: 
regular and static. The regular member function has ac¬ 
cess to all the instance data of the class, while the static 
function has no implicit data to access. This is because the 
regular member function receives a this pointer, which is 
sent as a hidden parameter, while the static function 
doesn't. The this pointer provides access to the class's 
data and virtual member functions. Without that pointer, 
the static function doesn't know how to find the appropri¬ 
ate instance data of the object. 


Figure 1 

callbacks 

Thunk code template for C++ member 

pop ax 

Save the return address 

pop bx 
mov cx, XXXX 

Load the "this” pointer’s segment on the stack 

push cx 
mov cx, XXXX 

Load the "this" pointer’s offset on the stack 

push cx 
push bx 

Put the return address back 

push ax 

jmp XXXX:XXXX 

Jump to the member function 


Listing 1 objthunk.h — Declaration of a thunkable 
class 


#i fndef OBJTHUNKJ 
#define OBJTHUNKJ 

#1f !(defined(_INC_WINDOWS) II defined( MIND0WS_H)) 

include <windows.h> 

#endif 

class Thunkable; // Forward Reference so we can define THUNK- 
PROC 

typedef void (CALLBACK Thunkable::* THUNKPROCKvoid); 

class Thunkable 
{ 

public: 

Thunkable(THUNKPROC Pointer): 
virtual -Thunkable(); 

operator FARPROCO { return ThunkProcedure; } 
private: 

// declare but don’t define 
Thunkable(const Thunkable&); 
const Thunkable &operator=(const Thunkable&): 

FARPROC MakeThunktTHUNKPROC lpmfnFunc); 
void FreeThunkCFARPROC lpfnFunc); 

FARPROC ThunkProcedure; 

}; 

#end1f OBJTHUNKJ 
/* End of File */ 
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Listing 2 objthunk.c — Implementation of C++ member callback thunks 

#include <windows.h> 

if (ot) 

#include <string.h> // for memcpyO 

{ 

memepytot, ObjThunk, 17); 

#1nclude "objthunk.h" 

*(int *)(ot+3) = SEGMENT(this); 

*(int *)(ot+7) = OFFSET(this); 

// not everybody supports FP macros well 

*(DWORD *)(ot+13) = *(DWORD *)&lpmfnFunc; 

ffdefine SEGMENT(ptr) ((unsigned shortK(unsigned longl(ptr) » 16)) 

PrestoChangoSelector(SEGMENT(ot), SEGMENT(ot)) ; 

#define OFFSET(ptr) ((unsigned short)(unsigned longMptr)) 

1 

return (FARPROCJot; 

// char array avoids structure packing issues 
static unsigned char 0bjThunk[17] = 

1 

{ 

void Thunkable::FreeThunk(FARPROC lpfnFunc) 

0x58, // pop ax 

{ 

0x5B, // pop bx 

if (lpfnFunc) 

0xB9, // mov cx, XXXX 

{ 

0x00, // Segment of this pointer 

PrestoChangoSelector(SEGMENT (1 pfnFunc) 

0X00, 

SEGMENT(lpfnFunc)); 

0x51, // push cx 

GlobalFree((HGL0BAL)L0W0RD( 

0xB9, // mov cx, XXXX 

G1obalHandle(SEGMENT (1 pfnFunc) ))); 

0x00, // Offset of this pointer 

1 

0X00, 

0x51, // push cx 

1 

0x53, // push bx 

Thunkable::Thunkable(THUNKPROC Pointer) 

0x50, // push ax 

{ 

0xEA, // jmp XXXX:XXXX 

ThunkProcedure = MakeThunk(Pointer); 

0X00, 0X00, 0X00, 0X00 

1 

}; 

Thunkable::~Thunkable() 

{ 

FreeThunk(ThunkProcedure); 

1 

FARPROC Thunkable::MakeThunk(THUNKPROC lpmfnFunc) 

{ 

char *ot = (char *)GlobalLock( 

Globa 1A11 oc(GMEM_FIXEDI GMEMJHARE 1 GMEMJOTJANKED, 
sizeof(ObjThunk) ) ); 

/* End of File */ 
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Associating an Object with a Callback 

The main obstacle to using a class member function as 
a callback lies in getting the this pointer passed along 
with the other parameters. Unfortunately, Windows 
doesn't understand the concept of C++ and its classes; it 
was originally written with only C and Pascal in mind. In 
some of the later functions (mostly those that were cre¬ 
ated for version 3.1 and later), there is a mechanism for 
passing a DWORD along with a function pointer. You can 
store an object pointer in DWORD, which the callback func¬ 
tion can then use to access the appropriate object. Most 
of the Enum...() functions are able to use this technique. 
(A good article on this approach appears on the Microsoft 
Development Library CD-ROM: 'Calling All Members: 
Member Functions as Callbacks," by Dale Rogerson.) 

This technique is less than satisfactory. You still cannot 
supply a non-static member function to the enumeration 
function, since it passes the DWORD argument explicitly, not 
as a C++ member function call. Instead, you have to give 
the enumeration function the address of a static class 
member function, which can then cast the DWORD into an 
object pointer of the appropriate type and access the 
members of that class. This technique also limits your abil¬ 
ity to take advantage of inheritance, since a static mem¬ 
ber function cannot be virtual. 

The ideal solution would cause Windows to know 
about the this pointer and pass it to the member callback 
function implicitly. Borland International's ObjectWindows 
Library (OWL) uses a clever scheme that involves a 
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method of object thunking. It creates a small area in 
memory that loads the ES-.BX registers with a pointer to 
the object and then calls an intermediary function to 
translate the pointer into a this pointer. (A good article by 
Brett Kelts in the May 1993 issue of Windows Tech Jour¬ 
nal describes this method.) 

This approach too, unfortunately, is somewhat flawed; 
it doesn't completely hide the thunking mechanism from 
the programmer, and it requires the use of an intermedi¬ 
ary function to load the this pointer and distribute the 
function call. A better solution would make using member 
callback functions as easy as creating C callback functions. 

Playing with the Stack 

The ultimate solution involves creating a thunk (a dy¬ 
namically created smidgen of code) that puts the this 
pointer on the stack when Windows calls the C++ class 
member callback function. That's the only way to emulate 
the actual process by which C++ compilers pass the this 
pointer to the member functions. 

'How do you get the this pointer onto the stack?' Well, 
it turns out that, in most cases, the this pointer is the very 
last argument pushed on the stack. Here's what the stack 
usually looks like upon entry into a function: 

Parml 

ParmN 

this 

Return Address 
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Listing 3 timer.h — Timer: a class with a member 
callback function 


#ifndef TIMER_C 
(/define TIMER_C 

(/include "objthunk.h" 

class Timer : public Thunkable 
{ 

public: 

TimerO; 

-TimerO; 

int StartdJINT Timeout); 

int StopO; 

protected: 

virtual void CALLBACK TimerProc(HWND Window, 

UINT Message, UINT Timerld, DWORD Ticks); 

private: 

UINT Timerld; 

}; 

(fendi f 

/* End of File */ 


It would be a simple matter to write a bit of thunking 
code that could pull the return address off the stack, put 
the this pointer in, replace the return address, then jump 
to the member function. The assembly language to ac¬ 
complish this is shown in Figure 1. By creating this thunk 
on the fly and passing the address of the thunk to Win¬ 
dows as a callback procedure address, you force the 
thunk to place the correct this pointer on the stack just 
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before jumping to the C++ class member callback func¬ 
tion. 

Note that the code in Figure 1 assumes it is dealing 
with the large memory model, and therefore with far data 
and code. It would take little work to modify this for vari¬ 
ous models, but I would recommend using this technique 
only with the large memory model, as Windows requires 
its callbacks to be FAR and, since you won't know exactly 
where execution is coming from, you need this to be FAR 
as well. 

The thunking code in Figure 1 can insert the this 
pointer into the stack, but how do you pop it off when the 
member function returns? Flere is where I make use of the 
PASCAL keyword. The primary differences between a func¬ 
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tion declared as CDECL (the default) and one declared as 
PASCAL have to do with the order in which parameters are 
passed on the stack and who pops those parameters off 
when the function is finished. CDECL calling functions push 
the parameters ieft-to-right, call the target function, then 
pop the parameters off the stack. PASCAL calling functions 
push the parameters right-to-left, call the function, then 
rely on the function to pop the parameters off the stack 
for it. 

The PASCAL calling convention is usually preferable, as it 
puts the code to pop off the parameters in only one place, 
at the end of the called function, rather than after every 
call to the function. It saves space in the code, and also 
tends to run faster because the compiler can generate 
code that uses the 80x86's return 
statements to efficiently remove the 
parameters. Not only that, but if the 
called function knows about the pa¬ 
rameters and pops them off itself, 
then you don't have to worry about 
getting rid of the this pointer in¬ 
serted by the thunk; the function will 
take care of the parameters, includ¬ 
ing the hidden this pointer, itself. 

This doesn't mean that you can't 
use this technique with CDECL func¬ 
tions. It just means that if you wish 
to use CDECL functions, you will need 
to replace the return value on the 
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Listing 4 timer.c — Implementation of timer callback class 

//include "timer.h" 

int Timer::Stop() 

Timer::Timer() 

{ 

: Thunkablet(THUNKPROO&Timer: :TimerProc), Timerld(0) 

if(Timerld) 

{ 

{ 

} 

Ki 1 ITimer(NULL. Timerld); 

Timerld = 0; 

Timer::~Timer() 

{ 

StopO: 

return TRUE; 

} 

else 

} 

return FALSE; 

} 

int Timer::StarttUINT Timeout) 

{ 

// dummy virtual callback -- override in your own class. 

if(Timerld) 

void CALLBACK Timer::TimerProc(HWND /*hWnd*/, 

StopO: 

UINT /‘Message*/, UINT /‘TimerlD*/, DWORD /‘Time*/) 

Timerld = SetTimer(NULL, 0, Timeout, 

(TIMERPROC ) (FARPROC)*thi s) : 

{ 

return Timerld; 

} 

} 

/* End of File */ 


stack with the address of something that will pull the this 
pointer off the stack and restore the original return ad¬ 
dress. This is something of a pain to do, and since all the 
Windows function callbacks are supposed to be PASCAL 
anyway, there's no real point in doing it. There's also a 
potential problem with the combination of CDECL functions 
that return structures (described in the next section). 
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Pitfalls and Requirements 

A few pitfalls and requirements go along with this tech¬ 
nique. First, it requires that the this pointer be the last 
parameter pushed on the stack before the member func¬ 
tion is actually called. Fortunately, this is usually the case. 
An exception occurs when the Borland compiler (either 
v3.1 or v4.0) compiles a CDECL member function that re¬ 
turns a structure; in this case, the last parameter pushed 
on the stack is the address of the temporary space into 
which the structure is to be returned. The this pointer is 
the parameter immediately before that. However, as noted 
earlier, there's no real need for applying the thunking 
technique to CDECL functions, so there's no real need to 
worry about this. 

It's also important to note that PASCAL functions can't 
take variable arguments. That was the reason for chang¬ 
ing the parameter ordering and having the calling func¬ 
tion remove the parameters in the first place; a CDECL func¬ 
tion can spend time looking at the parameters it needs 
without having to worry about popping anything it 
doesn't know about off the stack. The caller, which knows 
what was placed on the stack, can do all the worrying. 

Another problem with this technique is that pointers to 
C++ class member functions are not necessarily simple 
pointers at all. Because of the complexities of multiple in¬ 
heritance and virtual functions, C++ compilers may imple¬ 
ment pointers to member functions as structures that 
could even be larger than a 32-bit pointer! As with any 
method that involves tinkering with the stack, this tech¬ 
nique is vulnerable to changes in the way the compiler 
generates code. However, the code has been tested suc¬ 
cessfully with classes not involving multiple inheritance for 
both Borland C++ v4.0 and Symantec C++ v6.0. Microsoft 
C++ v8.x fails to even compile the code successfully, a 
problem discussed in the Practical C++ column in this is¬ 
sue. 

Finally, as was mentioned earlier, the code that accom¬ 
panies this article assumes the large memory model which en¬ 
tails both far data and code. In general, I tend to recommend 
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using the large model at all times in Windows. The small 
savings incurred by using other memory models is usually 
not worth all the extra hassle of ensuring appropriate 
sizes for pointers. 

Implementation 

Windows already lets you create and delete thunks, via 
the functions MakeProclnstanceO and FreeProcInstanceO. 
One problem with these functions is that it is easy to allo¬ 
cate a thunk and forget to free it, thereby creating a re¬ 
source leak in Windows. Tying thunk creation and dele¬ 
tion to C++ object creation and deletion can help prevent 
this problem, objthunk.h (Listing 1) defines Thunkable, a 
class whose constructor dynamically creates a C++ class 
member callback thunk, and whose destructor frees up 
that thunk. 

Unlike C, C++ contains a fairly strict type system. You 
cannot, for example, just cast a pointer to a member func¬ 
tion into a void * or vice versa. What you can do, as 
outlined in The Annotated C++ Reference Manual, is cast a 
member function pointer into another member function 
pointer if both pointers refer to classes of which one is 
unambiguously derived from the other. That leads to the 
second purpose of class Thunkable, to provide a base class 
from which you can derive classes whose member func¬ 
tions can be cast to type THUNKPROC without blatantly violat¬ 
ing C++ type safety rules. 

Note that the definition of THUNKPROC in objthunk.h uses 
CALLBACK rather than PASCAL in declaring the type of the 



Figure 2 C++ member callback demo 


member function callback. CALLBACK is defined in windows.h 
to be FAR PASCAL, and is simply a slightly more mnemonic 
alternative for this situation. Also, to correctly handle re¬ 
source cleanup, class Thunkable should correctly handle the 
cases of copying and assignment by creating duplicate 
copies of the thunk code, as needed. To keep the size 
down, the example code simply makes copying and as¬ 
signment illegal by declaring private versions of the copy 
constructor and assignment operator and not defining 
them. 

objthunk.c (Listing 2) contains the implementation of 
class Thunkable. The actual creation of the thunk is rather 
easy. It's a simple matter to copy a template that looks 
like the thunking code to newly allocated memory, fill in 
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the variable portions, then return the address of that 
memory. The tricky part is allowing the data that you allo¬ 
cate and fill to be executed. Normally, Windows is very 
picky about what areas of memory are data that can be 
read from and written to, and what areas are code that 
can be executed. When you allocate memory, you are 
normally creating data that can't be executed. Here's 
where the function PrestoChangoSelectorO comes in. It al¬ 
lows you to change the data to code and vice versa. 

Using the Thunkable Class 

To use class Thunkable, you derive a class from it that 
contains a member function you want to use as a callback 
procedure, timer, h (Listing 3) declares such a class, creat¬ 
ing a timer class whose virtual function gets called every 
time the corresponding Windows timer fires, timer, c (List¬ 
ing 4) contains the implementation of class Timer. 

As timer, c shows, the constructor of the class you de¬ 
rive from Thunkable must initialize the base class with the 
address of the member function that you want to use as a 
callback, casting it to type THUNKPROC. In this case, timer, c 
passes the address of a virtual function called 
Timer::TimerProc(). With this code in place, you can ignore 
the complexities of thunking by just deriving a class from 
class Timer and overriding the virtual function 
Timer::TimerProc() with your own function. 


A simple application included on the code disk (see the 
table of contents page for code availability) creates a class 
derived from Timer that simply updates a static text control 
with an incrementing count each time the timer fires. Fig¬ 
ure 2 shows this demonstration application in action. 

Summary 

C++ and Windows form, at best, an uneasy alliance, 
and C++ member callback functions constitute one of the 
areas where no solution is without drawbacks. Although 
the thunking algorithm presented here has some limita¬ 
tions and is vulnerable to changes in compiler code gen¬ 
eration, it has the advantage of being easier and more 
natural to use than other C++ thunking methods that 
have been published. 
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Member Function Pointers 


Despite our best editing efforts, we simply did not have enough room in this 
issue for all the articles we wanted to run. That being the case, I heroically 
volunteered to throw out my normal column and only run the bug of the 
month. Next month's column will resume the Windows User Interface MANager 
(WUIMAN) project where I left off. 

Bug++ of the Month 

I lost plenty of time on compiler bugs this month. As mentioned in another 
article in this issue, Borland C++ v4.0 can lock up my machine if I hit Ctrl-C 
during a make - certainly a worthy contender for bug of the month. However, 
since that bug is already covered, I want to focus here on Microsoft C++ v8.00c 
(also called Visual C++ vl.5) and its problems with pointers to member func¬ 
tions. 

Member function pointers in C++ are useful for some of the same reasons 
that function pointers are useful in C. For example, if you wanted to build an 
opcode interpreter in C++, a natural design might call for an Interpreter class 
whose member functions implemented the various opcode instructions; the in¬ 
terpreter would fetch an opcode, and use it to jump into a table of member 
function pointers to execute the code that implemented the opcode instruction. 

It is not unusual to need to declare a pointer to member function type 
before you finish declaring the corresponding C++ class. Fortunately, C++ lets 
you declare a forward reference for a class, so you can declare a member 
function pointer for a class that has not been defined yet, like this: 

class Thunkable; 

typedef void (Thunkable::* THUNKPROCKvoid); 

This is perfectly legal code, yet all versions of Microsoft C++ fail to compile it, 
emitting the following error message: 

bugl.c(3) : error C2644: basis class 
’Thunkable’ for pointer to member 
has not been defined 
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Listing 1 mscbug.c — Sample pointer to member 
function code 


/* Microsoft C/C++ v8.00c 
compile with: 

cl -DSTRICT /c /nologo /W3 /vmg /Zp /GAs /GEsme \ 

/AS /Tpmscbug.c 

produces error: 

mscbug.c(39) : error C2642: cast to pointer to \ 

member must be from related pointer to member 

*/ 

ifinclude (windows.h> 
class Thunkable: 

typedef void (CALLBACK Thunkable::* THUNKPROCXvoid): 

class Thunkable 
{ 

public: 

ThunkableCTHUNKPROC Pointer): 

-Thunkable!); 

operator FARPROCO { return ThunkProcedure: } 
private: 


Both Borland C++ and Symantec C++ compile this decla¬ 
ration correctly with no problem, so what's going on? Al¬ 
though this error message makes it sound like the pro¬ 
gram is not legal C++, it in fact turns out that Microsoft 
C++ by default assumes that you will never declare a 
member function pointer before declaring the correspond¬ 
ing class, and it takes advantage of this assumption to 


more easily generate efficient code. If you want Microsoft 
C++ to accept all legal types of member function pointer 
forward references, yog have to tell it so explicitly with 
the obscure /vmg option. I am sure that Microsoft will 
never classify this behavior as a bug. In my book, though, 
any time a compiler requires you to specify extra options 
in order to get a legal program to compile, that is a bug. 
At the very least, Microsoft's error message should refer 
you to the /vmg option and not make it sound like your 
code is illegal. 

I ran into this bug a year or so ago, so at that time I 
added /vmg to my default set of options for compiling code 
with the Microsoft C++ compiler. However, I got stymied 
again recently, while working on the code for Craig Ar- 
nush's article in the current issue. Even with the /vmg op¬ 
tion, Microsoft C++ v8.00c would not compile his code. I 
finally boiled the code down to the small example in 
mscbug.c (Listing 1), which elicits the following error mes¬ 
sage from Microsoft C++ v8.00c: 

mscbug.c(39) : error C2642: cast to 
pointer to member must be from 
related pointer to member 

In this sample code, class Timer is derived from class Thunk¬ 
able, which defines a kind of generic pointer to member 
functions of class Thunkable, like so: 
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typedef void (CALLBACK Thunkable::* 

THUNKPROCHvoid); 

Because I'm using the /vmg option, the compiler accepts 
this declaration. What the compiler does not accept, how¬ 
ever, is that line 39 casts a pointer to a member function 
of a different type to type THUNKPROC. The error message is 
totally misleading, since the the pointer being cast is defi¬ 
nitely to a member function of a related class. 

Until the initial ANSI C++ draft hits the streets, the main 
reference for what is and what is not legal C++ is gener¬ 
ally The Annotated C++ Reference Manual, by Ellis and 
Stroustrup, often called simply the ARM. Here is what the 
ARM has to say about casting member function pointers: 

A pointer to member may be explicitly converted into a 
different pointer to member type when the two types are 
both pointers to members of the same class or when the 
two types are pointers to member functions of classes one 
of which is unambiguously derived from the other. 

By my reading of this text, there is no requirement that 
the functions be of the same type, and the code in ques¬ 
tion seems to me to comply with the latter restriction, that 
the two types are pointers to member functions of related 
classes. Furthermore, both Borland and Symantec compil¬ 
ers compile and execute Craig's code with no problem. I 
reported this bug to Microsoft's online support, but they 
disagree that this is a bug, so it seems unlikely to change 
in future versions of the compiler. Interestingly enough, 


Listing 1 continued 


FARPROC ThunkProcedure; 

}; 

class Timer : public Thunkable 
{ 

public: 

TimertUINT uTimeout, HWND Window=NULL); 

-Timer!); 
protected: 

virtual void CALLBACK TimerProcfHWND hWnd. UINT uMsg, 

UINT idTimer, DWORD dwTime); 

private: 

UINT idTimer: 

}; 

Timer::Timer(UINT uTimeout, HWND Window) 

: Thunkable((THUNKPROO&Timer::TimerProc) /* line#39! */ 

{ 

idTimer = SetTimer(Window, 0, uTimeout, 

(TIMERPROCX FARPROC)*thi s): 

} 

/* End of File */ 


the support person I talked to did not distinguish the rules 
for implicit type converson of member function pointers 
(which are quite strict) from the rules for explicit type con¬ 
version (casts); I wonder if the compiler designers made a 
similar mistake. In any case, Microsoft's compiler will discour¬ 
age Microsoft C++ programmers from using pointers to 
member functions for the forseeable future. □ 
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Comm Coprocessor Speeds Windows Serial Applications 


COMMteiligence is a new hardware and software so¬ 
lution to the problem of bottlenecked PC serial communi¬ 
cations. The COMMteiligence coprocessor board handles 
all COM port interrupts, buffering data for the PC, and 
freeing the PC from having to handle the realtime needs 
of serial communication. The coprocessor boards are 
available with either two or four PC-compatible COM 
ports. The onboard CPU communicates with the PC 
through the ISA bus, using dual-ported memory. 

The coprocessor board can handle more than just 
simple interrupt processing and character buffering. You 
can also use the COMMteiligence Developer's Kit to 
offload your own custom serial communications code (to 
handle high-level protocols such as Kermit or ZModem, 


for example) onto the coprocessor board. The board can 
actually emulate a DOS environment, so you can create 
a . exe with Borland or Microsoft C/C++ and download it 
to the coprocessor board, moving even more of your se¬ 
rial communications processing off of the main CPU. You 
can place programs in EPROM, download them into on¬ 
board flash EPROM, or download them into RAM at each 
power-up. 

A COMMteiligence system with two PC-compatible 
COM ports costs $395; the COMMteiligence Developer's 
Kit costs $375. For more information, contact Drumlin, 
3447 Ocean ViewBlvd., Glendale, CA91208, 

(818) 244-4600; FAX (818) 244-4246. 


WindowsMAKER Professional Adds OWL v2.0 Support 


Blue Sky Software has announced the addition of 
OWL v2.0 support (OWL v2.0 is the application frame¬ 
work that ships with Borland C++ v4.0) to Windows¬ 
MAKER Professional v5.0. WindowsMAKER Professional 
is GUI prototyper and code generator that lets users cre¬ 
ate Windows applications interactively. The package of¬ 
fers Visual Basic- like code editing and the ability to 
preview and test run the application before compiling. 
Switch-lt Code Generation Modules (SIMs) let the user 


choose the type of code to generate for a given user in¬ 
terface. 

WindowsMAKER Professional v5.0 costs $995, and in¬ 
cludes the ANSI C SIM (for Windows, Win32s, and Win¬ 
dows NT); additional SIMs cost $499 each. For more 
information, contact Blue Sky Software Corporation, 

7486 La Jolla Blvd., Suite 3, La Jolla, CA 92037, 

(800) 677- 4WIN or (619) 459-6365; FAX (619) 459-6366. 


WinPath Utility Provides Updatable Windows Path 


WinPath is a new utility that gives users and program¬ 
mers the ability to inspect and modify Windows' environ¬ 
ment variables, such as the execution path. The included 
utility provides an interactive method to modify environ¬ 
ment variables, and Windows programs can access the 
program via DDE. Unlike DOS, WinPath is not limited to 


127 characters per line, an especially frustrating limit for 
the PATH= variable. 

WinPath vl .0 costs $29.95; site licenses and a DOS 
version are also available. For more information, contact 

Anchor Software, Inc, P.O. Box 124, Cheswlck, PA 15024, 
(412) 274-6504; FAX (412) 274-5010. 


Genus Upgrades DOS Graphics Kits 

Genus Microprogramming has upgraded its GX Devel¬ 
opment Series of toolkits to feature: direct support for 
over 50 SVGA chipsets, SVGA chipset detection, high 
color and true color video modes (15/16/24-bit color, at 
resolutions up to 1280x1024), increased VESA support, 
mode X resolution support, multiple SVGA pages, SVGA 
hardware panning and scrolling, enhanced virtual mem¬ 
ory management, improved color conversion and dither¬ 
ing, reduced DGROUP requirements, 16-bit 
protected-mode support, and reduced code overhead. 
These new features apply to all the toolkits, but individ¬ 
ual toolkits have particular improvements as well. 

PCX Toolkit v6.0 (provides PCX image manipulation) 
now features 24-bit PCX file support, direct DCX file sup¬ 
port (used by many fax programs), and new and updated 
utilities (display, capture, cut, scroll, translate, convert, 
and more). GX Text v3.0 (which provides bitmapped text 
in graphics mode) now features stroked font support, an 
additional 35 Postscript style fonts in six different sizes, 


italic and shadowed font attributes, a stroked font con¬ 
version utility, and third-party support (TrueType, Laser¬ 
Jet soft fonts, BGI stroked fonts, etc.). GX Printer vl .5 
now offers the ability to print higher resolution display 
modes, and a faster black-and-white printing mode for 
faster 2-color printing. GIF Toolkit vl .5 offers the new fea¬ 
tures listed in the previous paragraph. GX Graphics v3.0 
(a complete graphics library) offers faster drawing primi¬ 
tives. GX Effects v3.0 (for multimedia-style special effects 
and animation) now provides more special effects (fades 
and wipes), increased sound adaptor support, and flic file 
animation. 

PCX Toolkit v6.0 costs $249, GX Text v3.0 costs 
$149, GX Printer vl .5 costs $349, GIF Toolkit vl .5 costs 
$249, GX Graphics v3.0 costs $249, and GX Effects v3.0 
costs $199. For more information, contact Genus Micro¬ 
programming, 1155 Dairy Ashford, Suite 200, Houston, 
TX 77079, (800) 227-0918 or (713) 870-0737. 
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Pinpoint Analyzer Features Inter-Process Debugging 


PinPoint Analyzer is a new programming tool that 
lets programmers interactively examine the execution 
flow of their programs, particularly with multiple applica¬ 
tions running simultaneously. Pinpoint works with appli¬ 
cations made up of programs with client/server 
relationships, DDE, OLE, and other inter-program commu¬ 
nications. Windows 3.1 and Windows NT projects are 
fully supported. 

PinPoint uses existing debug information to automat¬ 
ically instrument all function entries and exits as part of 
the code compilation process. When the instrumented 
programs run, their flow and interaction is time-stamped 
and captured on disk by the PinPoint Analyzer, a sepa¬ 
rate program with its own window. Using the PinPoint 


Analyzer, programmers can see the program's flow in 
real time or review it after the fact. 

The Analyzer lets you search, filter, collaps, and expand 
the levels of functions, all in real time. Also, the Analyzer's 
source code browser Immediately displays the code associ¬ 
ated with a suspected problem. PinPoint lets you set break 
points that can halt program execution automatically, even 
with complex, multi-program criteria. Control can then be 
passed to a conventional single-step debugger, if necessary. 

PinPoint Analyzer costs $199. For more information, 
contact Avanti Software, Inc, 385 Sherman Avenue, Unit 
6, Palo Alto, CA 94306-1840, (800) 758-7011 or 
(415) 329-8999; FAX (415) 329-8722. 


Postman's Sort Available for Windows 

The Postman's Sort (described in the August 1992 is¬ 
sue of The C Users Journal) lets you sort large amounts of 
data in time proportional to the file size. Robert Ramey Soft¬ 
ware Development is now shipping the Postman s Sort De¬ 
veloper's Kit v2.25, which implements this algorithm, both 
as a standalone sorting program and as Windows and 
Windows NT DLLs. 


The Postman's Sort Developer's Kit costs $149. For 
more information, contact Robert Ramey Software 
Development, 3949 1/2 Foothill Road, Santa Barbara, CA 
93110,(805)569-3793 


Windows SNMP API Specification Available 


An industry group of network management vendors, 
applications developers, and users has released a stand¬ 
ard API for creating vendor- independent, interoperable 
network management applications running under Win¬ 
dows. The WinSNMP API gives Windows developers 
easy access to the services of Simple Network Manage¬ 
ment Protocol (SNMP) engines, which are used to man¬ 
age devices on local area networks, wide-area networks, 
and internetworks. 


The WinSNMP API specification is available via 
anonymous FTP from various sites, including Sun- 
Site.enc.edu, microdyne.com, and rh1no.m1crosoft.com. The 
group's mailing list is UinSNHPeMicrodyne.COM. You can sub¬ 
scribe to the working group by sending a 'subscribe me' 
message to HinSNMP-request@Microdyne.COM. 


Visual SlickEdit vl.O Offers GUI Editor Language 


Visual SlickEdit vl .0 is the successor to SlickEdit, a 
multi-platform program that was the first programming 
editor available for Windows NT. Visual SlickEdit is a con¬ 
figurable graphical programmer's editor with an object- 
oriented C-style macro language, and a built-in dialog 
editor. Visual SlickEdit's dialog editor lets you create 
event-drive dialog boxes. Besides the standard Windows 
controls, the dialog editor offers spin controls, gauges, 
drive lists, file lists, and directory lists. You can also cre¬ 
ate additional controls. You can create macro source 


code by recording steps; the macro record also records 
interaction with dialog boxes. Visual SlickEdit works 
alone or as an enhancement to your compiler's IDE. It in¬ 
cludes Brief and Emacs emulations and provides special 
support for most compilers and programming languages. 

Visual SlickEdit vl .0 is available for Windows NT on 
Intel, MIPs, and Alpha AXP machines, and also for Win¬ 
dows 3.1. For more information, contact MicroEdge Inc, 
P.O. Box 18038, Raleigh, NC 27619, (919) 790-1691 or 
(800) 934-EDIT; FAX (919)872-5586. 


MemCheckfor DOS Offers Extended Library Checking 


StratosWare is shipping MemCheck v3.0 Professional 
for DOS, an error detection and prevention tool for C 
and C++ programmers. Requiring no source code 
changes, MemCheck v3.0 detects memory overwrites 
and underwrites, memory leaks, heap corruption, stack 
overwrites, out-of- memory conditions, and other mem¬ 
ory errors. The new version now detects memory over¬ 
writes and leaks, even in third-party libraries, whether 
source code is available or not. The new version also pro¬ 


vides faster execution, enhanced detection of stack and 
static variable overwrites, and easier integration for C++ 
programmers. A new mouse-driven MemCheck control 
panel makes it easy to select all options. 

MemCheck v3.0 Professional for DOS costs $139. For 
more information, contact StratosWare Corporation, 
1756 Plymouth Road, Suite 1500, Ann Arbor, Ml 48105, 
(313) 996-2944; FAX (313) 747-8519. 
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HELP-EASE Provides WinHelp Development Environment 


HELP-EASE is a help authoring tool for Windows that 
features a WYSIWYG text editor and a specialized help 
project file editor. You can import RTF or ASCII text and 
both bitmap and metafile graphics are supported. HELP- 
EASE maintains an internal database that lets you estab¬ 
lish hypertext links with the mouse. It supports 
keywords, macros, browse sequences, and build tags. 


and automatically generates context strings. HELP-EASE 
lets you treat help source as a group of topics. Icons sup¬ 
port topic insertion, deletion, and splitting. 

HELP-EASE vl .2 costs $289, and includes a spelling 
checker. For more Information, contact Premiere Event Soft¬ 
ware, P.O. Box 177, Noravss, GA 30091, <404) 368-0172. 


WINLITE Squeezes Windows .exes 

Rosenthal WINLITE is a utility that compresses a Win¬ 
dows .exe, resulting in disk space savings. For example, 
the program compressed the 180Kb Windows Solitaire 
game to less than 77Kb. You simply give Rosenthal WIN- 
LITE a Windows executable and the output is a function¬ 
ally identical executable that is smaller - no additional 


drivers or modification to source code or linking are re¬ 
quired. 

Rosenthal WINLITE costs $149. For more informa- 
ton,contact Rosenthal Engineering, P.O. Box 1650, San 
Luis Obispo, CA 93401, (805) 541-0910. 


Microsoft FORTRAN and MASM Get NT Support 


Microsoft FORTRAN PowerStation 32 development 
system for Windows NT is an NT version of Microsoft's 
32-bit FORTRAN development system. The 32-bit flat 
memory model of Windows NT allows FORTRAN pro¬ 
grams to access up to 4Gb of memory. Microsoft has 
also added NT support to the Microsoft Macro Assembler 
Professional Development System v6.11. This version 
supports Windows NT, Windows 3.1, and 16- and 32-bit 
DOS applications. The new version is NT hosted and sup¬ 


ports the Pentium and NT-compatible utilities, Including 
CREF and H21NC. Applications for NT developed with 
MASM v6.11 can now be assembled, linked, and de¬ 
bugged completely within Windows NT. 

MASM v6.11 costs $249. FORTRAN PowerStation 32 
for Windows NT costs $795. For more information, con¬ 
tact Microsoft Corporation, One Microsoft Way, Redmond, 
WA 98052-6399, (206) 882-8080; FAX (206) 93MSFAX. 


Intel Ships Plug and Play Development Kits 


Plug and Play is the name for a new class of PC add¬ 
in cards that users can install simply by inserting the 
card; Plug and Play means an end to the tedious fussing 
with IRQ levels and port numbers currently associated 
with adding a card to a PC. Intel is now shipping the Plug 
and Play Kit for MS-DOS and Windows. 

The kit includes a DOS driver that automatically de¬ 
tects and configures a Plug and Play ISA add-in card, in¬ 
terface libraries that provide device drivers with access to 
card configuration information, a configuration utility 
that helps users configure traditional ISA cards, and refer¬ 
ence manuals. To facilitate the design of Plug and Play 
ISA add-in cards, the kit also includes a VHDL description 
for an ASIC implementation. 


Another kit, the Plug and Play BIOS Enhancements 
Kit, contains BIOS software that automatically detects 
and configures PCI and Plug and Play ISA add-in cards. 
Software is available in source form, allowing BIOS ven¬ 
dors and OEMs to integrate this Plug and Play software 
into their existing BIOS products. 

Both kits are openly licensed to PC hardware manu¬ 
facturers, including platform OEMs and add-in card ven¬ 
dors. Each kit includes a registration form, 
documentation, and free telephone support. For more in¬ 
formation on the Plug and Play kits, call Intel's literature 
center at (800) 548-4725 or write for Intel Literature 
Packet #F8P01, P.O. Box 7641, Mt Prospect IL 60056-7641. 


Dis Doc Disassembly Tool Moves to Windows 


Dis Doc for Windows is a Windows version of Dis 
Doc Professional, a tool for disassembling code. Dis Doc 
for Windows can disassemble Windows, OS/2, .obj, .exe, 
. com, and BIOS files. The product can output its disassem¬ 
bly into a window where you can make changes, view 
code, search, etc. The new software also supports disas¬ 
sembly of Pentium instructions. 


Dis Doc for Windows costs $299; Dis Doc Profes¬ 
sional (DOS) costs $249. The company's BBS offers a free 
demonstration and data sheet. For more information, 
contact RJSwantek, Inc, 33 Spencer Brook Rd„ New Hart¬ 
ford, CT 06057, (800) 336-1961; BBS (203) 953-6196. 
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Robert Mashlan writes: 

I recently re-read your Q&A column in the January 1993 issue of Win- 
dows/DOS Developer's Journal. One question that you answered was about 
drawing an MDI (Multiple Document Interface) child window without the mini¬ 
mize and maximize boxes, and without the system menu. You had offered as a 
solution to clear these bits during the UM_NCCREATE message as a way to avoid 
painting the window with these attributes. 

Anyhow, although your solution works well, there is a little trick you may 
want to add to your bag. Under both Windows 3.1 and 3.0, windows, h defines a 
flag to SetUindowPosO. If you call SetUindowPosO with the SUP_DRAUFRAME flag, it 
will recalculate and draw the non-client areas of the window after you change 
style bits that affect them. 

Robert Mashlan 
rmashlan@mash.bouIder.co.us 


Paul replies: 

W ell, I tried it and your idea works great. It is now a proud resident in the 
bag o' tricks. Another API function I did not try when I answered the 
original question was RedrawUindowO. This handy newcomer (it first appeared in 
version 3.1) gives the programmer a lot of control for invalidating windows. I 
used it with the flags 

RDW_FRAME | RDWJNVALIDATE 

and supplied NULL for both the invalid rectangle and region. You can use either 
the SetUindowPosO trick or the call to RedrawUindowO when the MDI child receives 
the UM_CREATE message - both produce the desired results, with no flicker. 


eE3= 

Borland C++ v3.1 

Symantec C++ v6.0 


Microsoft C/C++ v8.0 


Q From what I read in your column in the June 1992 issue I get the impres¬ 
sion that I can have a program wait in PeekMessage for a particular mes¬ 
sage. If this is the case, then this could solve a synchronization problem I am 
having in some of my programs. The problem is if I do a 


Paul Bonneau 


Send questions to Paul via internet as 

poul@rdpub.com 

from CompuServe: 

>INTERNET:paul@rdpub.com 
or in care of this magazine at: 

1601 W. 23rd St, Suite 200 
Lawrence, KS 66046-2700. 

Paul answers all electronic 
communications but is unable to 
respond personally to hard copy/disk 
messages. 


PeekMessage(&m$g, hWnd, MY_MESSAGE, 

MY_MESSAGE. PMJIELD) 

I hang Windows. Is there a way I can get my application to wait for a message 
without stalling Windows? 

Steve Schachter 
steves@mvision.com 


Paul was a developer of HyperChem, a molecular modeling system, and more recently, 
of Creative Writer, a word processor for children. He works for Microsoft Corporation as 
a Software Design Engineer. The opinions expressed in this column are Paul's alone 
and not those of Microsoft. 























A As you have discovered, filtering 
messages in PeekMessageO (or 
GetMessageO, for that matter) is error- 
prone. The problem is that hardware 
messages (mouse, keyboard, etc.) are 
serialized in a single system queue 
and can only be removed from the 
head of the queue. Thus if your ap¬ 
plication does not remove its mes¬ 
sage from the head, no other appli¬ 
cations can get their messages and 
the system no longer responds to 
user input. 


The simplest answer to your ques¬ 
tion is to enter a modal loop until 
you receive the message you are 
looking for. You could write a func¬ 
tion as follows: 

void WaitMsgtUINT win) 

{ 

MSG msg; 
do { 

GetMessage(&rasg, NULL, 0, 0); 

TranslateMessage(&msg); 
DispatchMessage(&msg); 

} 


while(msg.message != WM_QUIT 
&& msg.message != wm); 

} 

Your code would call UaitMsg(MY_MES- 
SAGE) whenever it wanted to wait for 
a particular message to arrive. A po¬ 
tential problem with this simple ap¬ 
proach, depending on the design of 
your application, is that your applica¬ 
tion will continue to receive user in¬ 
put, since messages are still being 
obtained from the queue and dis¬ 
patched to your application's win¬ 
dows. 

You can handle this on a per-win- 
dow basis by disabling the window 
before entering the loop, and re-ena- 
bling it before returning from 
UaitMsgO. This prevents that particu¬ 
lar window from receiving mouse or 
keyboard input while waiting for 
UaitMsgO to return. You only have to 
worry about non-child windows, 
since child windows inherit the en¬ 
abled/disabled property from their 
parents. Windows uses this type of 
modal loop when you call Message- 
BoxO or DialogBoxO. 

If for some reason your applica¬ 
tion cannot process any queued mes¬ 
sages while waiting for UaitMsgO to 
return, there is a third, more extreme 
approach. With some care, you can 
simply discard queued messages. 
uaitmsg.c (Listing 1) contains the code 
for a modified version of UaitMsgO. 
This version simply discards mes¬ 
sages unless they are for a window 
not belonging to the current applica¬ 
tion, or are paint ( UM_PAINT) messages. 

It seems strange, but an applica¬ 
tion will receive messages for the 
desktop window. The desktop win¬ 
dow does not belong to any particu¬ 
lar task - Windows does not have a 
daemon task supporting the desktop. 
But every window must be associ¬ 
ated with a task queue, so Windows 
sets the desktop window's queue to 
be that of the currently running ap¬ 
plication. Whenever a task switch oc¬ 
curs, Windows updates the task 
queue handle in the desktop window 
structure. As a result, the desktop 
window gets its messages from the 
message loop of whatever task hap¬ 
pens to be running. 


AccuSoft Image Format Library 4.0 
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Throwing away messages for the 
desktop window is not a good thing 
to do. Not only can it result in an 
ugly desktop (portions not getting re¬ 
freshed properly), but you can end 
up hanging the system. The version 
of UaitMsgO in Listing 1 gets the 
module handle of the current task 
and compares it with the module 
handle for the window destined to 
receive the current message (the 
desktop window belongs to the USER 
module). If they are different, the 
message is not for one of the appli¬ 
cation's windows, so UaitMsgO dis¬ 
patches the message to the intended 
window. 

UaitMsgO also has special code for 
UM_PAINT messages. UM_PAINT is not a 
real message, but is merely a bit 
(QS_PAINT, value 1x0120) that gets set 
in a field inside a task's message 
queue structure. If your application 
calls GetMessageO with no messages 
in the queue and this bit is set, Get¬ 
MessageO returns a UM_PAINT message. 
The only way to clear this bit is by 
validating the update region, either 
by calling ValidateRectO or Vali- 


dateRgnO, or by using the Begin - 
PaintO/EndPaintO pair. 

If you just discard UM_PAINT mes¬ 
sages, the bit never gets cleared, so 
the next time GetMessageO is called, lo 
and behold, your application gets an¬ 
other UM_PAINT message. This may not 
sound all that bad - since the mes¬ 
sages are polled from your main 
loop, not sent, other applications 
should still get a chance to run, right? 
Wrong. In general, if the current task 
has a message in its queue and calls 
GetMessageO or PeekMessageO, Win¬ 
dows will not allow a task switch to 
occur, so the current application will 
end up in an infinite loop. 

To avoid locking up the system in¬ 
side an infinite UM_PAINT loop, 
UaitMsgO calls ValidateRectO with an 
LPRECT parameter of NULL to validate 
the entire client area. The drawback 
is that your window is now in need 
of refreshing, and will look bad until 
UaitMsgO returns. I should also point 
out that your windows will still re¬ 
ceive some messages even if you dis¬ 
card all the messages in your input 
queue - specifically, your windows 


Listing 1 waitmsg.c 



/* waitmsg.c */ 

/* -- Function waits until a specific message Is */ 

/* received. */ 

/*****************************************************/ 
♦Include <w1ndows.h> 

♦Include <toolhelp.h> 

♦Include "waltmsg.h" 

void 

WaltMsgdJINT wm) 

/*****************************************************/ 
/* -- Return once specific message Is received. */ 
/* -- wm : Message to wait for. */ 

/*****************************************************/ 

{ 

MSG msg; 

TASKENTRY tke: 

tke.dwSIze = slzeof tke; 

TaskF1ndHandle(itke, GetCurrentTaskO); 
do 

{ 

If (!GetMessage(&msg. NULL. 0, 0)) 
break; 

If (ilsWlndow(msg.hwnd) 11 
GetClassWord(msg.hwnd. GCW.HMODULE) != 
(WORD)tke.hModul e) 

{ 

TranslateMessage(Amsg); 

D1spatchMessageC &msg); 

} 

else If (msg.message == WMJAINT) 

ValIdateRectCmsg.hwnd. NULL); 

} 

while (msg.message 1= wm); 

} 

/* End of File */ 


will still be bombarded with a large 
number of sent (as opposed to 


MultiLinl# for Windows is a Grand Slam for 
Connectivity Programming in Windows 


Whether as a programming tool or as a platform for 
developing connectivity solutions for your clients, MultiLink 
for Windows is a whole new ball game. 

MultiLink for Windows takes advantage of Microsoft® 
Windows' multitasking to provide multiuser capabilities on 
the Windows PC. This means that up to eight users (more 
in some situations) can actually share the CPU to run DOS 
applications from a 
terminal, workstation 
or PC emulating a 
terminal while the 
host Windows PC 
remains active and in 
use. Users sharing 
the PC can be local (in 
the same office) or 
remote (dialing in via 
modem from another 
office or another city). 

First a Programmer's Tool 

MultiLink for Windows lets you view the Windows desktop 
while programming in a DOS box . You can write or debug 
code from the DOS session at a terminal while watching the 
results on the Windows PC at your side. This means no 
more exiting your Windows session or switching to an 
inactive task. 



Second a Support Tool 

If you need to provide technical support or programming services to a 
client in another location, you can use MultiLink for Windows to access the 
system as a remote user via modem and terminal emulation to debug 
code or check configurations from your home or office. 

Third a Flexible Platform Choice for Development 
MultiLink for Windows is a flexible alternative to networking that 
provides fast, simple connectivity versus the com¬ 
plexity of a LAN. One example is the point-of-sale 
environment, where retail terminals may not require 
graphics, but back-office managers may wish to use 
Windows for data analysis or monitoring. The oppor¬ 
tunities for unique and exciting applications are endless. 
Score with a Winning Alternative 
MultiLink for Windows is a whole new ball game in 
affordability, ease-of-use, ease-of-development and 
connectivity. It is a tool for transition from the 
DOS standard to the Windows environment. It is a 
connectivity tool for sharing information and 
equipment without a network. Call The 
Software Link and get in the game. 

THE SOFTWARE LINK 

Creating Unbeatable 
Connectivity Solutions 


Call (404) 512-0705 

Fax (404) 512-7005 


MultiLink is a registered trademark of The Software Link. Microsoft is a registered trademark of Microsoft Corporation. Price, policies and 
specifications subject to change without notice. © Copyright 1993 The Software Link, Inc. 5575B Chamblee-Dunwoody Road, Suite 205, 
Atlanta, Georgia 30338 USA. Phone (404) 512-0705. Fax (404) 512-7005. 
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Listing 2 childmnu.c — 
Demonstration program for child 
window menus 


/*****************************************************/ 


/* childmnu.c */ 
I* -- Application demonstrates multiple menued child */ 
/* windows. */ 
/* -- To build: cc childmnu.c chlldmnu.rc */ 


/*****************************************************/ 


♦Include <w1ndows.h> 
♦Include <w1ndowsx.h> 
♦Include "chlldmnu.h" 


♦define cbBufMax 256 /* Generic string size. */ 


/* Globals. */ 

char szChlldClasst] = "ChlldClass"; 

char szHalnClass[] = "MalnClass": 

char szMa1nT1tle[] = "Menued Child Window Demo": 

HWND hwndMaln; /* Main window. */ 

HWND hwndActlve; /* Active child window. */ 


/* Prototypes. */ 

void CreateHybrld(HWND hwndParent); 

BOOL CALLBACK .export 
FDestroyHybr1d(HWND hwnd, LPARAM IParam); 

BOOL FIsHybr1d(HWND hwnd); 

HWND HwndNextHybrld(HWND hwndChlld); 

LRESULT CALLBACK .export 

LwHybrldWndProc(HWND hwnd. UINT wm. WPARAM wParam. 
LPARAM IParam): 

LRESULT CALLBACK .export 
LwMalnWndProc(HWND hwnd, UINT wm. WPARAM wParam. 
LPARAM IParam); 


♦Ifdef _BORLANDC_ 

♦pragma argsused 
♦endlf 

Int PASCAL W1nMa1n(HINSTANCE bins, HINSTANCE hlnsPrev. 
LPSTR lpsz, Int wShow) 

/*****************************************************/ 
/* -- Entry point. */ 


{ 


posted) messages generated by nor¬ 
mal user interaction with the other 
active applications in the system. For 
example, when an application calls 
SetFocusO, Windows sends a UM_KILL- 
FOCUS message (using SendMessageO) to 
the window losing the focus. 

Sent messages are delivered di¬ 
rectly, and so bypass the queue. It is 
definitely not a good idea to simply 
discard sent messages. Doing so can 
have an adverse affect on all win¬ 
dows, not just those of your applica¬ 
tion, and typically will result in a 
hung system. 


eE3= 

Borland C++ v3.1 

J Symantec C++ v6.0 


Microsoft C/C++ v8.0 


Q I need to be able to put menu 
bars on child windows, but the 
evil Windows API won't let me. 
Please save us!!! 

Ivan Figueredo 
CIS: 75460,2417 


A Before tackling your question, 1 
want to review some terminol¬ 
ogy. You can divide windows into 
two classes: child windows and top- 
level windows. Top-level windows 
can have menus and don't have par¬ 
ent windows (the desktop window is 
their parent window for most practi¬ 
cal purposes); they include either the 
US_OVERLAPPED or the HSJOPUP style bit. 
Child windows always have parents 
and cannot have menus; their style- 
bit field must include US_CHILD. 

Well, it is possible to do what you 
want, after a fashion, but I should 
warn you that child windows with 
menus lead to a strange user inter¬ 
face. The major problem is the key¬ 
board interface. When the user 
presses the Alt key, it highlights the 
first item on the menu bar of the ac¬ 
tive window. But when you have one 
or more child windows that possess 
menus, what is the active window? If 
you follow the MDI user interface, 
you will have an active top-level 
'frame' window as well as an active 
child window. Which window should 
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be considered the active one for han¬ 
dling the Alt key? 

Even if ail you want to do is place 
a menu at some arbitrary location in¬ 
side a top-level window by using a 
child window as the menu's place¬ 
holder, you still face the problem of 
including the child window's menu in 
the highlight order (when the user 
navigates through menu bar items 
using the arrow keys). You may be 
able to use a message filter hook to 


include the child window menu in 
the highlight order (see my article 
'Excel-Style Menu Navigation' in the 
September 1992 Windows/DOS Devel¬ 
oper's Journal), but I suspect it will be 
messy. 

The problem from a coding point 
of view is also non-trivial. Internally, 
Windows uses a structure that con¬ 
tains the information it must keep 
track of for each window (see the 
June 1992 Windows Q8A for details 


of this undocumented structure). One 
of the fields in that internal structure 
serves a dual purpose: for non-child 
windows, it contains the window's 
menu handle, but for child windows 
(which are not allowed to have 
menus), that field contains the child 
window's control ID (used in dialog 
boxes to identify which child window 
is sending messages). 

When Windows draws the non-cli¬ 
ent area of a window, it checks the 


Listing 2 continued 


MSG msg; 

WNDCLASS wcs; 

If (ihinsPrev) 

{ 

/* Register the main class. */ 
wcs.style = 0; 

wcs.lpfnWndProc = LwMainWndProc; 
wcs.cbClsExtra = 0; 
wcs.cbWndExtra = 0; 
wcs.hlnstance = bins; 

wcs.hlcon = LoadlconCNULL. IDI_APPLICATION); 
wcs.hCursor = LoadCursor(NULL, IDC_ARR0W); 
wcs.hbrBackground = (HBRUSH)(C0L0R_WINDOW + 1); 
wcs.lpszMenuName = MAKEINTRESOURCE(idmMain); 
wcs.lpszClassName = szMainClass; 
if (!RegisterClass(Awes)) 
return FALSE; 

/* Register the child class. */ 
wcs.lpfnWndProc = LwHybridWndProc; 
wcs.lpszMenuName = MAKEINTRESOURCE(idmChild); 
wcs.lpszClassName = szChildClass; 
if (!RegisterClass(&wcs)) 
return FALSE; 

} 

msg.wParam = 0; 

if ((hwndMain = CreateWindow(szMainClass, 
szMainTitle, WSJVERLAPPEDWINDOW, CWJSEDEFAULT. 
CWJSEDEFAULT. CWJSEDEFAULT, CWJSEDEFAULT. 

NULL, NULL, bins, NULL)) != NULL) 

{ 

ShowWindowChwndMain, wShow); 
while (GetMessage(&msg, NULL, 0, 0)) 

{ 

TranslateMessage(&msg); 
DispatchMessage(imsg); 

} 

} 

return msg.wParam; 

} 

LRESULT CALLBACK .export LwMainWndProc(HWND hwnd, 

UINT wm, WPARAM wParam, LPARAM IParam) 

/* -- Main window procedure. */ 

/★♦♦★A************************************************/ 

{ 

switch (wm) 

( 

default: 

break; 

case WM.COMMAND: 

if (wParam == idmFileNew) 

{ 

CreateHybrid(hwnd); 
return 0; 

) 

break; 

case WMJESTROY: 

/* Explicitly destroy hybrids. */ 
EnumChildWindows(hwnd, FDestroyHybrid, 0); 
PostQuitMessage(0); 
break; 



case WM.NCACTIVATE: 
if (wParam) 

{ 

if (hwndActive != NULL) 

DefWindowProc(hwndActive, wm, TRUE. 0); 

} 

else 

{ 

if (hwndActive != (HWND)(UINT)lParam && 
hwndActive != NULL) 

DefWindowProc(hwndActive, wm. FALSE. 

0 ); 

if (FIsHybrid((HWND)(UINT)lParam)) 
return TRUE; 

} 

break: /* End case WMJCACTIVATE. */ 


Tired of juggling with your 
serial port problems? 



Losing serial characters because of 
Windows" interrupt latencies? Are your 
comm applications running unbearably 
slow? Juggling a little code here, fiddling 
with an ISR there, and trying again? 

There's a better solution: * • 

COMMtelligence™ 



This RS232/RS485 board has a PC-compatible 
CPU dedicated to servicing interrupts from its 
four serial ports. Dual-port RAM, resident 
firmware, and 512K of RAM provide deeply 
buffered serial data to your Windows or DOS 
program - with no missing data. 


To supercharge applications, download custom programs 
onto the COMMtelligence board to perform protocol 
conversion, polling, or other front-end processing tasks. 

So quit juggling with your serial port problems. Get your 
application going by calling or FAXing for details today. 


^DRUMLIN 


3447 Ocean View, Glendale, CA 91208 


Phone 

FAX 
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Listing 2 continued 


case WMJSER: 

SetActiveWindow(hvmd); 
return 0; 

} /* End switch wm. */ 

return DefWindowProc(hwnd, wm, wParam, IParam); 

} 

void CreateHybrid(HWND hwndParent) 

/*****************************************************/ 
/* -* Create a new hybrid. */ 

/*****************************************************/ 
{ 

RECT rect; 

HWND hwndChild; 

char szBuf[cbBufHax]; 

GetClientRect(hwndParent. &rect); 
hwndChild = CreateWindow(szChi1dClass. NULL, 
WS.SYSMENU I WS.CAPTION | WS_CLIPSIBLINGS I 
WS.MAXIMIZEBOX | WS.MINIMIZEBOX | 

WS.THICKFRAME I WSJOPUP, 
rect.right / 4, rect.bottom / 4, rect.right / 2, 
rect.bottom / 2, hwndParent. NULL, 
GetWindowInstance(hwndParent), NULL); 
if (hwndChild != NULL) 

{ 

SetParentChwndChild, hwndParent); 
wsprintf(szBuf, "Child Xx", hwndChild); 
SetWindowText(hwndChild, szBuf); 

ShowWindowChwndChi 1 d. SWJHOWNORMAL); 

} 

} 

#ifdef _BORLANDC_ 

//pragma argsused 
#endif 

BOOL CALLBACK .export FDestroyHybrid(HWND hwnd, 

LPARAH IParam) 

/*****************************************************/ 
/* -- EnumChildWindowsO callback destroys all */ 


window's style attributes. If it is a top-level window, Win¬ 
dows then checks the menu handle member of the inter¬ 
nal window structure. If the menu handle member is not 
NULL, Windows draws the menu. But if the window is a 
child, then the menu handle member will never be 
checked, since it contains a control ID, not a valid menu 
handle. So, by definition, a true child window cannot pos¬ 
sess a menu. 

Okay, warnings aside, I did implement a demonstration 
application that manages multiple 'child' windows with 
menus. I put 'child' in quotes, since the windows have 
attributes of both child and top-level windows. One of the 
key aspects of a child window is that it is clipped to its 
parent. You cannot drag a child window outside its par¬ 
ent's client area. Other features include inheriting the par¬ 
ent's enabled state, so that when the parent is disabled, 
so is the child. But, as you have probably guessed, my 
'child' window does not possess the child window style 
attribute. To convince Windows that the window does 
possess a menu, you must use either the US_P0PUP or 
US_OVERLAPPED style. But how is it possible for a window to 
possess both child and non-child aspects? 

To answer this question I have to briefly discuss how 
Windows organizes the set of windows that exist at any 
1 oint in time. Conceptually, each window on the screen 
has four other windows associated with it: its next sibling 
window, its first child window, its parent window, and its 
owner window. The first three associated windows imple¬ 
ment Windows' internal tree of windows (see page 29 of 
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the June 1992 Windows/DOS Developer's Journal for more 
details). 

A popup window that is owned is tied to the window 
that owns it. When the owner window is hidden or icon¬ 
ized, Windows hides the popup. A popup maintains its z 
order relative to its owner; if a popup is directly on top of 
its owner, and another window is brought to the top, the 
new window will be on top of the popup as well. 

The boundary of a parent window's client area defines 
the rectangle that its child windows are clipped to, inde¬ 
pendent of the child window's style bits. The parent win¬ 
dow also controls the enabled/disabled state and even 
such details as icon placement (the position of a mini¬ 
mized child window). 

Associated with each window are its style bits. Win¬ 
dows examines the style bits when it determines such 
things as which window to activate when an arbitrary 
window is clicked with the mouse (the parent is activated 
when an enabled window with the US_CHILD attribute is 
clicked). And, as already mentioned, Windows consults the 
style bits when a window's non-client area is drawn to see 
if a menu should be drawn. 

You can create a hybrid window with characteristics of 
both child and popup windows by initially creating a 
popup window, and then calling SetParentO to change its 
parent window from the desktop window to the desired 
parent window. This is the heart of the demonstration ap¬ 
plication, childmnu.c (Listing 2). childmnu.rc (Listing B) is a 
resource file that defines a couple of menus, and childmnu.h 


Listing 2 continued 


/* hybrids. 


{ 

if (FIsHybrid(hwnd)) 
DestroyWindow(hwnd); 
return TRUE; 

} 

BOOL FIsHybridCHWND hwnd) 


/*****************************************************/ 
/* -- Return whether the window is a hybrid. */ 


{ 

char szBuf[cbBufMax]; 


if (GetWindowTask(hwnd) != GetCurrentTaskO) 
return FALSE; 

GetClassName(hwnd, szBuf, sizeof(szBuf) - 1); 
return !lstrcmp(szBuf, szChildClass); 

} 


LRESULT CALLBACK .export LwHybridWndProc(HWND hwnd. 

UINT wm, WPARAM wParam, LPARAM lParam) 

/***************************************************** j 

/* -- Hybrid window procedure. */ 

/A****************************************************/ 

{ 

DWORD IwStyle; 

HWND hwndSibling; 
char szBuf[cbBufMax]; 

switch (wm) 

{ 

default: 

break; 


case WMJCACTIVATE: 
if (wParam) 

{ 

hwndActive = hwnd; 

DefWindowProc(hwndMain, wm, TRUE, 0); 
} 
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(Listing 4) contains the menu constants. The application's main 
window possesses a single menu item, 'New', that creates 
a new child window with its own menu (I will call that a 
'hybrid' window), childmnu.c creates the hybrid with a 
non-client area, the same as a standard top-level window 
would have. The application manages the active hybrid so 


Listing 2 continued 


else 

{ 

if ((HWND)(UINT)lParam == hwndMain) 
return TRUE; 

if (!FIsHybridi(HWND)(UINT)lParam)) 

DefWindowProcthwndMain, wm, FALSE, 0); 

} 

break; 

case WM_SYS KEY DOWN: 

if (wParam == VK.MENU) 

{ 

SetActiveWindowChwndMain); 
PostMessagefhwndMain, wm, wParam, TParam); 
return 0; 

} 

break; 

case WM_DESTROY: 

/* Activate another hybrid if there is one. */ 
if (hwnd ** hwndActive) 

{ 

hwndActive = NULL; 

if ((hwndSibling ■ HwndNextHybrid(hwnd)) != 
NULL) 

SetActiveWindow(hwndSi bl i ng); 

) 

break; 

case WMJOMMAND: 

/* Prove that the hybrid's menu works. */ 
wsprintf(szBuf, 

"Menu Xd of popup Xd was picked", 
wParam X 10, (wParam X 100) / 10); 
MessageBox(hwndMain, szBuf, szMainTitle. 

MB_0K); . 
break; 

case WM_WINDOWPOSCHANGING: 

/* Use child style when iconic to prevent */ 

/* desktop from poking around sides of icon. */ 
lwStyle = GetWindowLong(hwnd, GWL_STYLE); 
if ((lwStyle J (USJOPUP I WS.CHILD)) == 
(Islconic(hwnd) ? WS_P0PUP : WS_CHILD)) 
SetWindowLongthwnd, GWL_STYLE, 
lwStyle * (WS.CHILD I WS_P0PUP)); 

break; 

} 

return DefWindowProc(hwnd. wm, wParam, 1Param); 

) 

HWND HwndNextHybrid(HWND hwndChild) 

I **************************** *************************j 

I* -- Return next hybrid sibling. */ 

/*****************************************************/ 
{ 

HWND hwnd; 

for (hwnd * GetWindowthwndMain. GW_CHILD); 
hwnd 1 = NULL; 

hwnd = GetWindowthwnd, GW_HWNDNEXT)) 
if (hwnd 1= hwndChild S& FIsHybrid(hwnd)) 
return hwnd; 
return NULL; 

} 

/* End of File */ 


that, for example, when another application's top-level 
window is active and the demonstration program's main 
window is clicked with the mouse, the previously active 
hybrid is reactivated. Figure 1 shows the demonstration 
program running with two child windows, one minimized, 
and one clipped by the parent window. 

In childmnu.c, UinMainO performs the normal initializa¬ 
tion of registering a class for the main window. It also 
registers a window class for the hybrids. The main win¬ 
dow is then created, and the function falls into its main 
loop until the main window is destroyed and GetMessageO 
returns NULL when it retrieves the UM_QUIT message. 

The next routine in childmnu.c, LwMainUndProcO, is the 
window procedure for the main window. When it receives 
a UM_COMMAND message from the 'New' menu item, it calls 
the helper procedure CreateHybridO to create a new hy¬ 
brid window. CreateHybridO creates a popup window one- 
quarter the size of, and centered on, the main window's 
client area. Given that the hybrid's parent is the main win¬ 
dow, it doesn't matter whether the hybrid is created with 
the USJOPUP or the USJVERLAPPED attribute. I picked USJOPUP 
because it takes less time to type. 

After creating the initial hybrid window, CreateHybridO 
calls SetParentO to change the hybrid's parent to the main 
window. In addition to giving the hybrid window a differ¬ 
ent parent window, SetParentO repositions the hybrid rela¬ 
tive to its new parent. In the case of a popup, whose par¬ 
ent is originally the desktop, this means its position, which 
was at (x, y) in screen coordinates, will now be at position 
(x, y) relative to its new parent's client area. CreateHybridO 
does not supply the USJISIBLE attribute to CreateUindowO, 
so the user will not see the flash when SetParentO reposi¬ 
tions the window. SetParentO does not change a window's 
style attributes, so at this point the hybrid has the desired 
characteristics. CreateHybridO then sets the hybrid's title 
and displays the hybrid with a call to ShowUindowO. 

Returning to LwMainUndProcO in childmnu.c, when the 
main window receives a UMJESTROY message, it enumer¬ 
ates its child windows and explicitly destroys the hybrid 
children. Normally, Windws destroys child windows after 
destroying their parent. But because the hybrids are not 
true child windows, Windows' window manager gets con¬ 
fused and corrupts its internal tree of windows. Explicitly 
destroying the hybrids sidesteps the problem. ! pass 
FDestroyHybridO to EnumChildUindowsO to destroy the hy¬ 
brids. It uses the helper function FIsHybridO to determine 
if the current window is one of the hybrids and, if so, calls 
DestroyUindow(). FIsHybridO checks that the given win¬ 
dow's class name is that of the hybrid class. It also checks 
that the window belongs to the current task, so that 
FIsHybridO can properly return FALSE if it is given a win¬ 
dow from another task that just happens to have the 
same class name as the hybrid class. 

The UMJCACTIVATE cases of LwMainUndProcO (the main 
window procedure) and LwHybridUndProcO (the window 
procedure for hybrid windows) work together. Since the 
hybrids have the US_P0PUP attribute, Windows' window 
manager treats them as ordinary popup windows when it 
comes to activation. Without special code, clicking on the 
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main window would deactivate any active hybrid, and, 
conversely, clicking on a hybrid would deactivate the 
main window. Both of these cases are confusing, espe¬ 
cially for users accustomed to the MDI user interface. In 
the first case, after clicking on the main window, there will 
be no active child. In the latter, after clicking on a hybrid, 
it will appear as if the hybrid is a popup window. This is 
where the MM_NCACTIVATE cases in the two window proce¬ 
dures come into play. 

At first I thought it would be sufficient to always keep 
the main window the active window when the demonstra¬ 
tion program was the active application. My idea was to 
keep track of the 'display-as-active' hybrid, and always 
show it as active without actually allowing it to become 
the active window. The problem with this idea is that the 
user then cannot access the hybrid window's menu. As 
soon as the user clicked on a hybrid's menu, its window 
procedure would reactivate the main window, which 
would cancel menu mode. 

Instead, I decided that when the demonstration pro¬ 
gram is the active application, I would display the main 
window as active and always display a hybrid as active 
(assuming at least one hybrid exists), regardless of 
whether the active window is really the main window or 
the hybrid. The code also remembers the last hybrid dis¬ 
played as active so that if another application is active, 
and the user clicks on the main window, the last active 
hybrid will be reactivated. The drawback with this approach is 
that when the demonstration program is the active application. 


Listing 3 childmnu.rc — Resource difinitions for 
child window menu demo 


/*****************************************************/ 
I* childmnu.rc */ 

/* -- Menu definitions for menued child demo. */ 

^***************************************************** j 

^include <windows.h> 
ifinclude "childmnu.h" 

/* Frame window menu. */ 
idmMain MENU 
BEGIN 

POPUP "JFile" 

BEGIN 

MENUITEM ”4New", idmFileNew 
END 
END 

/* Child window menu. */ 
idmChild MENU 
8EGIN 

POPUP "Dummy 1” 

BEGIN 

MENUITEM "41 don’t do much". idmDummyll 

MENUITEM "4Neither do I". idmDummyl2 

END 

POPUP "Dummy 2” 

BEGIN 

MENUITEM "41 don’t do much". idmDumny21 

MENUITEM "4Neither do I". idmDummy22 

END 
END 
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Listing 4 childmnu.h — Menu IDs for demo 
program 


/*****************************************************/ 
/* childmnu.h */ 

/* -- Menu ID’s for menued child demo. */ 

/***★**★*********★★★******★**★*★■*•★★★****★***★****★★***/ 
//define idmMain 1000 /* Main menu id. */ 

//define idmFileNew 1001 /* File/New menuitem ID. */ 

//define idmDummy 1002 /* Dummy menuitem ID. */ 

//define idmChild 2000 /* Child menu id. */ 

//define idmDummyll 2011 /* Dummy menus. */ 

//define idmDummyl2 2012 
//define idmDummy21 2021 
//define idmDummy22 2022 
/* End of File */ 


the user will not know which window is the real active 
window, and therefore cannot know which window's 
menu will be highlighted by pressing the Alt key. 

So, time for another kludge. I decided to add code to 
the hybrid window procedure to trap presses of the Alt 
key, and to activate the main window and post the mes¬ 
sage to it. This effectively redirects the Alt key press to the 
main window. This at least presents a consistent user in¬ 
terface, even though it means a hybrid window's menu 
can only be accessed with the mouse, not the keyboard. 

Before explaining how the activation handling code 
works, I need to point out what might be a documenta- 
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tion error for the UM_HCACTI/ATE message (or might just be 
a lack of documentation). According to the SDK, the only 
parameter supplied with this message is a Boolean value 
for wParam. If wParam is non-zero, the window becomes ac¬ 
tive; else, it becomes inactive. But 1 Pa ram contains mean¬ 
ingful information as well. The high-order word contains a 
Boolean value that is non-zero if the window is iconic, and 
the low-order word contains the window handle being de¬ 
activated (if wParam is non-zero), or being activated (if 
wParam is zero). This is exactly the same information sup¬ 
plied with the UM_ACTIVATE message, which makes it seem 
suspiciously like an oversight in the documentation. 

Windows sends the UM_NCACTIVATE message before 
UM_ACTIVATE, and it is this message that causes DefUindow- 
ProcO to draw the window's non-client area as either ac¬ 
tive or inactive. By the time a window receives Ml^ACTI¬ 
VATE, the drawing has been done. A window can refuse to 
be deactivated by returning FALSE to the UM_NCACTIVATE 
message. Returning TRUE to the message allows Windows 
to change the active window. 

With all that in mind, I can now describe the activation 
code. When LwHybridUndProcO receives a UM_NCACTIVATE with 
a non-zero wParam, it stores the window handle in the 
global variable hwndActive, since this window is about to 
become the active hybrid window. It then calls DefUindow- 
ProcO with the main window handle, a UM_NCACTIVATE mes¬ 
sage, and a wParam of TRUE to display the main window as 
active. 

When a hybrid window is being deactivated (wParam is 
zero), the code checks if the window being activated is the 
main window (this would happen when a user clicks on 
the main window itself). If it is, the case returns TRUE, by¬ 
passing the call to DefUindowProcO at the end of LwHy¬ 
bridUndProcO. This lets the main window be activated, and 
prevents displaying the hybrid as inactive. If the window 
being activated is not the main window, the code uses the 
FIsHybridO helper function to see if it is a sibling hybrid. If 
it is not, then some other popup or top-level window is 
being activated, and the main window needs to be dis¬ 
played as inactive. Once again, DefUindowProcO is called di¬ 
rectly to accomplish the task, this time with a wParam of 0. 

Returning to the code in LwMainUndProcO: if the main 
window is being activated and there was a previous active 
hybrid, in which case the global variable hwndActive is non- 
NULL, LwMainUndProcO calls DefUindowProcO to redisplay the 
hybrid window as active. If the main window is being de¬ 
activated, and the window being activated is not the ac¬ 
tive hybrid child, LwMainUndProcO calls DefUindowProcO to 
display the active hybrid as inactive. The code then checks 
if the window being activated is any hybrid, and returns 
TRUE if so. This prevents the call to DefUindowProcO at the 
end of LwMainUndProcO from displaying the main window 
as inactive, and allows the hybrid to become the active 
window. 

This completes the discussion of LwMainUndProcO, but 
there is more to say about LwHybridUndProcO, the window 
procedure for hybrid windows. The Alt key redirection is 
handled when a UM_SYSKEYD0UN message arrives, just the way I 
described it. When a hybrid is destroyed, the UM_DESTR0Y case 
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checks to see if it is the active hybrid, and if there is an¬ 
other hybrid, makes it the active window, calling HwndNex- 
tHybridO to find a sibling. HwndNextHybridO loops over the 
children of the main window, if it finds one that passes 
the FIsHybridO test and is not the same as the window 
being destroyed, it returns the sibling's window handle; 
otherwise, it returns NULL The UM_COMMAND case in the hybrid 
window procedure puts up a message box when a hy¬ 
brid's menu item is picked, just to demonstrate that the 
hybrid's menu works. 

The last message handled by LwHybridUndProcO is 
UM_MINDOMPOSCHANGING. Windows sends this message when¬ 
ever a window's x, y, or z position is about to change, 
including transitions to and from the iconic state. I handle 
this message because when Windows draws a minimized 
window (an icon), the background of the parent of that 
minimized window bleeds through in all the areas of the 
icon that were designed to be transparent. That effect oc¬ 
curs even if there are other windows between the parent 
and the iconized window. For top-level windows, the effec¬ 
tive parent is the desktop. But if the window is a child, 
then the background of its parent window is displayed in¬ 
stead. So the code changes a hybrid's style attribute to 
US_CHILD when the hybrid is iconized, and changes it back 
to US_P0PUP when the icon is restored. 

There are couple of random notes I would like to men¬ 
tion before ending. The first is that you cannot use func¬ 



Figure 1 Demonstration of child window menus 


tions like IsChildO and GetParentO with the hybrids. Both 
these functions check the style attribute, and do not con¬ 
sider windows with US_P0PUP or US_OVERLAPPED as proper 
children. The other is the issue of MDI. MDI does a lot 
more to manage children than the code in my demonstra¬ 
tion application. So why not just use MDI? The problem is 
that MDI relies on being able to access MDI children 
through consecutive control IDs, starting with a value sup¬ 
plied by the programmer. This will not work when menu 
handles are stored in a UND structure's menu handle mem¬ 
ber. I could not think of a way to fake out the MDI man¬ 
ager, but if someone does, I would love to hear how. □ 
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■ Tech Tips 



Persistent Windows 


Preserving Window Size and Position between Invocations 


Jason M. Rinn 
Winter Park, FL 32792 


There are various ways a windows program can renew its pre¬ 
vious state. However, none of them seemed to be quite what I was looking for. 
Some programs, such as Windows Write, basically save their "normal" window 
size (normal in the sense of the ShowUindowO argument SU_N0RMAL). If you close 
the window while it is maximized, then reopen it, the new window will not be 
maximized. Other programs, like Quicken, take it one better: in these cases, if 
the window was closed maximized, it will open at normal size, then suddenly 
maximize - with a distracting flicker I might add. 

Windows Clock is a definite improvement, but I've not seen any information 
on how it works. If you either maximize or minimize it, then close and reopen 
it, it will open in the state you left it in, and still save its 'normal' size. I would 
prefer a minimized clock in the lower right-hand corner of the desktop, but 
Clock refuses to remember its minimized position. 



Edited by 
Leor Zolman 


Please send us your best 
tricks and hacks -those 
clever pieces of code to 
make things work the 
way they should! You’ll 
receive at least $50 for 
each tip that we print 
Send your submissions to.- 
Tech Tips 
Leor Zolman 
74 Marblehead Street 
North Reading, MA 01864 
leor@bdsoft.com. 


Leor Zolman wrote BDS C, the first C compiler targeted exclusively for personal com¬ 
puters. Leor is currently an instructor on UNIX topics for Boston University's Corporate 
Education Center, a regular contributor to Sys Admin magazine and "Tech Tips" editor 
for Windows/DOS Developer's Journal. His first book, Illustrated C, was published 
by R9D Publications, Inc. in 7 992. He may be contacted at 74 Marblehead St., North 
Reading, MA 01864, or on Usenet/Internet as: leor@bdsoft.com. 



















75 


It turns out that, in the dark corners of the Windows 
API, I found exactly what I wanted. The function GetUin- 
dowPlacementO allows you to know normal position and 
size, minimized position, and even maximized position. 
SetWindowPl acementO will then set the window back to 
what it was, even setting the minimized position, which is 


apparently how Windows Clock works. I have placed func¬ 
tions to do the work to save and renew placement to a 
.ini file in plac.c (Listing 1) and placment.h (Listing 2). No¬ 
tice that the last parameter to RenewPl acementO is a BOOL, 
which specifies whether or not to renew the minimized 
position. 


Listing 1 plac.c 


/* Plac.c - Routines to save window placement, and then restore it again. 

/‘Maximized position*/ 

* The routines are passed a HWND for the window and a filename. 

ptPos.x=GetPrivateProfilelnt(POSNAME. "MaxX", 0. IpszAppFile); 

* RenewPlacement also has a BOOL parameter to decide whether to set 

ptPos.y=GetPrivateProf1 1 elnt ( POSNAME, "MaxY", 0. IpszAppFile); 

* minimized position. Setting it to false will duplicate 

wpPos.ptMaxPosition=ptPos; 

* Windows Clock's behavior. 

/‘Window position and size*/ 

*/ 

rcPos.top=GetPrivateProf1 1 elnt ( POSNAME. "Top". 

linclude <windows.h> 

GetSystemMetr1cs(SM_CYSCREEN ) / 8. IpszAppFile); 

♦include <stdlib.h> /* for itoa*/ 

rcPos.1eft=GetPrivateProfi 1 elnt ( POSNAME, "Left". 

♦include "placment.h" 

GetSystemMetr1cs ( SM_CXSCREEN ) / 8. IpszAppFile); 

♦define POSHAME "Position" /‘Section title*/ 

rcPos.bottom=GetPrivateProfi1elnt ( POSNAME,"Bottom", rcPos.top*7, 1 pszAppFi 1 e ) ; 
rcPos.right=GetPrivateProfi 1 elnt ( POSNAME, "Right", rcPos.left*7, IpszAppFile); 

/* WritePrivateProfilelnt: 

wpPos.rcNormalPosltlon=rcPos; 

* Provides a symmetric opposite to GetPrivateProfilelnt. 

/‘Restore everything*/ 

* Parameters: 

SetWindowPlacement(HWindow, iwpPos ) ; 

* lpszSection: Section Title Name. 

* IpszEntry: Entry to write to. 

} 

* IToWrite: Int value to write. 

/‘SavePlacement: Saves the window placement. Including 

* lpszF11ename:Name of .INI file to write In. 

‘Normal size, position of icon(minimized position), and current state 

* Return: 

*(SW NORMAL, SW MAXIMIZED, or SW MINIMIZED) as returned from GetWindowPlacement 

* non-zero if funstion successful, zero otherwise. 

* 

*/ 

* Parameters: 

BOOL WritePrivateProfi1eInt(LPCSTR lpszSection, LPCSTR IpszEntry, UINT iToWrite 

* HWindow for window to restore 

,LPCSTR IpszFIlename) 

{ 

char str1ng[120]; /‘buffer string for Int to string conversion*/ 

* IpszAppFile for name of file used to store position 
*/ 

void SavePlacement(HWND HWindow, LPSTR IpszAppFile) 

return WritePrivateProfileStringdpszSection, IpszEntry, 

{ 

ItoadToWrite, string, 10), IpszFilename); 

WINDOWPLACEMENT wpPos; 

} 

/* RenewPlacement: Returns the window to the placement last saved, including 

POINT ptPos; 

RECT rcPos; 

* Normal size, position of icon(minimized position), and current state 

wpPos.length=sizeof(wpPos); /‘set size of structure*/ 

* (SW NORMAL. SW MAXIMIZED, or SW MINIMIZED) as returned from GetWindowPlacement 

/‘Get all the placement information*/ 

* to be passed on to SetWindowPlacement 

GetWindowPlacement(HWindow, &wpPos ) ; 

* Placement: 

/‘Save window state(maximized, minimized or retored)*/ 

* HWindow for window to restore 

* IpszAppFIle for name of file used to store position 

WritePrivateProf11eInt(POSNAME, "ShowCmd". wpPos.showCmd, IpszAppFile); 

* SetMin determines whether or not position of minimized window is restored 

/‘Minimized position*/ 

*/ 

ptPos=wpPos.ptMinPositi on; 

void RenewPlacement(HWND HWindow, LPSTR IpszAppFIle, BOOL SetMin) 

WritePrivateProfileInt(POSNAME, "MinX", ptPos.x, IpszAppFile); 

{ 

WINDOWPLACEMENT wpPos; 

WritePri vateProf ilelnUPOSNAME, "MinY", ptPos.y,IpszAppFile); 

POINT ptPos; 

/‘Maximized position*/ 

RECT rcPos; 

ptPos=wpPos.ptMaxPosition; 

WritePrivateProfi1elnt(POSNAME, "MaxX". ptPos.x, IpszAppFile); 

wpPos.length=sizeof(wpPos); /‘set size of structure*/ 

WritePrivateProfileInt(POSNAME, "MaxY", ptPos.y, IpszAppFile); 

/‘flag to restore minimized position*/ 

/♦window position and size*/ 

if (SetMin) wpPos.flags=WPF_SETMINPOSITION; 

rcPos=wpPos.rcNormalPosition; 

else wpPos.flags=0: 

WritePrivateProfi 1 elnt(POSNAME. "Top", rcPos.top, IpszAppFile); 

/‘Get window state(maximized, minimized or retored)*/ 

WritePrivateProf11eInt(P0SNAME, "Left", rcPos.left, IpszAppFile); 

wpPos.showCmd=GetPrivateProfi1elnt(POSNAME. "ShowCmd". SW.SHOWNORMAL. 

WritePrivateProfileInt(POSNAME, "Bottom", rcPos.bottom. IpszAppFile); 

IpszAppFIle): 

WritePrivateProf11eInt(POSNAME, "Right", rcPos.right. IpszAppFile); 

/‘Minimized position*/ 

) 

ptPos.x=GetPrivateProfileInt(POSNAME. "MinX", -1, IpszAppFile); 
ptPos.y=GetPrivateProfi1elnt(POSNAME, "MinY", -1,IpszAppFile); 
if (ptPos.x==-l || ptPos.y==-l) wpPos.flags=0; 
wpPos.ptMinPosition=ptPos; 

/* End of File */ 
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Listing 2 placment.h 


/* placment.h - Header file for plac.c 

* Designed to be used by a C or C++ program, even though placment is in C. 
*/ 

#ifdef _cplusplus /‘Allows for use by C++ and is ignored by C*/ 
extern "C" { 

#endif 

BOOL WritePrivateProfileInt(LPCSTR IpszSection, LPCSTR IpszEntry. 

UINT iToWrite, LPCSTR IpszFilename); 
void SavePlacementCHWND HWindow, LPSTR AppFile); 
void RenewPlacementtHWND HWindow, LPSTR AppFile, BOOL SetMin); 

#ifdef _cplusplus 

): 

#endif 


Listing 3 rsizec.c 


/* 

* rsizec.c: 

* Sample windows app which restores its original normal size, 

* position of minimized icon, and state(min- max- or normal) 

* using plac.c routines by Jason M. Rinn. 

* (Based loosely on generic.c from the Waite Groups WindowsAPI Bible) 
*/ 


//define W1N31 
//include <windows.h> 

//include <string.h> 

//include "plac.h" /‘for the placement routines*/ 

//define APPNAME "renewsiz" /‘name of application, used for window class*/ 

//define APPFILE "renewsiz. ini "/‘name of file to save placement to*/ 

//define OUTMSG "Close and reopen this window, it will remember its size!" 


long FAR PASCAL .export WndProc (HWND, UINT, WPARAH, LPARAM); 


int PASCAL WinMain (HINSTANCE hlnstance, HINSTANCE hPrevInstance, 
LPSTR IpszCmdParam, int nCmdShow) 

{ 

HWND hWnd; 

MSG msg; 

WNDCLASS wndclass; 


if 

{ 


(IhPrevInstance) /‘Register new window class if no previous instance*/ 


wndclass.style 
wndclass.1pfnWndProc 
wndclass.cbClsExtra 
wndclass.cbWndExtra 
wndclass.hlnstance 
wndclass.hlcon 
wndclass.hCursor 
wndclass.hbrBackground 
wndclass.IpszMenuName 
wndclass.1pszClassName 


= CS.HREDRAW I CSJREDRAW; 
= WndProc; 


= hlnstance; 

= LoadlconCNULL, IDI.APPLICATION); /‘Default Icon*/ 
= LoadCursorfNULL, IDC.ARROW); /‘Standard Cursor*/ 

= GetStockObject(WHITE_BRU$H); 

= NULL; /*No Menu*/ 

= APPNAME; 


if (!RegisterClass (Awndclass)) return FALSE; 

} 

/‘Create a window of default size, since previous size is restored anyway*/ 
hWnd = CreateWindowtAPPNAME, APPNAME, WSJJVERLAPPEDWINDOW, CWJJSEDEFAULT, 
CWJSEDEFAULT, CWJJSEDEFAULT, CWJJSEDEFAULT, NULL, NULL, 
hlnstance. NULL); 


/‘This is where Show Window usually goes*/ 

RenewPlacementthWnd, APPFILE, TRUE);/*restore previous size */ 
UpdateWindow(hWnd); /‘and force window draw*/ 

whi1e(GetMessage(&msg, NULL, 0, 0)) /‘Standard message loop*/ 

{ 

TranslateMessaget&msg); 

DispatchMessage(Jmsg); 
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The only remaining problem is to 
figure out where in the Windows 
creation/destruction process to do 
the saving and restoring of window 
placement. I started with a simple 


SDK-style C program. RenewPlacementO 
was easy - it simply replaced the 
normal call to ShouUindouO. The obvi¬ 
ous place for SavePlacement() is in re¬ 
sponse to UM_DESTROY, but many windows 


: : ■■■■ i . 

Listing 3 continued 


return msg.wParam; 

} 

long FAR PASCAL _export WndProc (HWND hWnd, UINT iMessage, 

WPARAM wParam, LPARAM lParam) 

{ 

HDC hdc; 

PAINTSTRUCT ps; 

switch(iMessage) 

{ 

case WM_PAINT: /*Paint one line of text.*/ 
hdc=BeginPaintihWnd. &ps); 

TextOutthdc, 0, 0, OUTMSG, strlen(OUTMSG)); 

EndPaintthWnd. &ps); 
return 0; 

case WM_DESTROY: /*Save placement if window is destroyed*/ 

SavePlacementthWnd, APPF1LE); 

PostQuitMessage(O); 
return 0; 

case WM_ENDSESSION: /*Save placement if the Windows system closes down*/ 
SavePlacementChWnd, APPFILE); 
break; 

} 

return DefWindowProcthWnd, iMessage. wParam, lParam); 

} 

/* End of File */ 


Listing 4 rsizec.mak 


t . 

t RENEWSIZ.MAK make file 

#... 

WINLINK=tlink /c In /Tw /Le:\bc\lib 
WINLIB=import mathws cws 
WINCC=bcc -c -w-par -W -2 

rsize.exe ; rsizec.obj plac.obj 

$(WINLINK) c0ws+plac+rsizec, rsize, NUL, f(WINLIB), rsize 

plac.obj: plac.c placment.h 
J(WINCC) -1$(INCLUDE) plac.c 

rsizec.obj; rsizec.c placment.h 
$(WINCC) -I$(INCLUDE) rsizec.c 


Listing 5 

rsize. def 

NAME 

rsize 

DESCRIPTION 

'Sample program that automatically restores last size/position' 

EXETYPE 

WINDOWS 

STUB 

'WINSTUB.EXE' 

CODE 

PRELOAD MOVEABLE DISCARDABLE 

DATA 

PRELOAD MOVEABLE MULTIPLE 

HEAPSIZE 

1024 

STACKSIZE 

8192 
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Listing 6 rsize.cpp 


1/ rsize.cpp - Test program for routines to save window placement. 

// It will remember the state it was in, as well as positions of all its states. 
#define WIN31 
#include <windows.h> 

#include <owl.h> 

#include <string.h> 

#include "placment.h" //include header for placement routines 
//define APPFILE "renewsiz.ini" 

//define OUTMSG "Close this window, and it will remember its placement" 

//Generic application object 
class TMyApp : public TApplication 
{ 

public: 

TMyAppCLPSTR AName, HINSTANCE hlnstance, HINSTANCE hPrevInstance, 

LPSTR lpCmdLine, int nCmdShow) 

: TApplication(AName, hlnstance, hPrevInstance, lpCmdLine, nCmdShow) {}; 
virtual void InitMainWindowO; 

)i 

//A class for a window which will restore its placement, 

//including minimized position. Simply inherit from this class 
//instead of TWindow. 

//Redefines WM_SH0UWINDOU and CanClose. 

_CLASSDEF(TRenewWindow) 
class TRenewWindow : public TWindow 
{ 

public: 

TRenewWindow!PTWindowsObject AParent, LPSTR ATitle): TWindow(AParent, ATitle) 
,first(TRUE) {}; //Set first to allow intercepting call to WM_SH0WWIND0W 
virtual void WMShowWindow(RTMessage)=[WM_FIRST+WM_SHOWWINDOW]; 
virtual BOOL CanCloseO; 

BOOL first; //Whether or not this is the first call to WM_SH0WWIND0W. 

}; 

//When the window is first displayed by ShowWindow, the size and placement are 
//restored from the last saved placement, 
void TRenewWindow::WMShowWindowtRTMessage msg) 

{ 

TWindow::DefWndProc(msg); 

//Renew placement only on the first message, since RenewPlacement will 
//also cause another WM_SH0WWIND0W to be sent, 
if (first) ( 
first=FAL$E; 

RenewPlacementtHWindow, APPFILE, TRUE); 

} 


//Save placement whenever the window is closed. 

BOOL TRenewWindow::CanCloseO 
{ 

SavePlacementtHWindow, APPFILE); 
return TWindow::CanClose(); 

} 

//Application specific window object. Just displays string at top of window. 
_CLASSDEF(TMyWindow) 
class TMyWindow : public TRenewWindow 
{ 

public: 

TMyWindowtPTWindowsObject AParent, LPSTR ATitle) 

: TRenewWindowtAParent, ATitle) {}; 
virtual void Paint(HDC PaintDC, PAINTSTRUCT _FAR & Paintlnfo); 

}; 

//Just paint a single line of text on the screen 

void TMyWindow::Paint(HDC PaintDC, PAINTSTRUCT _FAR & /‘Paintlnfo*/) 

{ 

TextOut(PaintDC, 0, 0. OUTMSG, strlen(OUTMSG)); 

} 

//Everything from here on is required for an OWL program and is standard, 
void TMyApp::InitMainWindow() 

{ 
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Listing 6 continued 


MainWindow = new TMyWindow(NULL. Name); 

} 

int PASCAL WinMain(HINSTANCE hlnstance, HINSTANCE hPrevInstance. 
LPSTR lpCmdLine. int nCmdShow) 

{ 

TMyApp MyAppC'Window Placement Example", hlnstance, hPrevInstance, 
lpCmdLine, nCmdShow); 

MyApp.RunO; 
return MyApp.Status; 

} 


programs (such as Quicken, to my 
everlasting annoyance) assume it's 
the only message you have to re¬ 
spond to when a program ends. 

Don't forget that if the user exits 
Windows, you get a UM_ENDSESSION in¬ 
stead. rsizec.c (Listing 3), rsizec.mak 
(Listing 4), and rsize.def (Listing 5) 
complete a short program, based on 
generic, h from the Waite Group's 
Windows API Bible, that demonstrates 
this process. 

I originally thought I was done 
programming at that point. Just to 
make sure, I wrote a simple OWL 
program to do the same thing. I put the placement code 
in a class called TRenewUindow so I could inherit new win¬ 
dow classes. Deciding where to place the call to SavePlace- 
mentO was even easier than for the C version. A Windows 
object always calls the member function CanCloseO on any 
closure, including a WM_ENDSESSION. Then, the problem 
struck. It turns out you can't replace the call to ShowWin- 
dow() (it's because the member function ShowO is not a 
virtual function, so the ShowO function of the base class 
will always be called by MakeUindowO). I did try to redefine 
the CreateO function and call RenewPlacementO after calling 
the base function. The window appeared in the default 


position, then jumped to the stored position. Unfortu¬ 
nately, I had reproduced Quicken's solution. 

In fact, I was stuck for quite a while. I tried to catch all 
the window messages that I knew would be sent when 
the window was first created, hoping I could stop ShowUin- 
dowO's effects. The best I could do was to set all the posi¬ 
tions and sizes before ShowUindowO, but the window was 
always returned to normal state before I could change it. 
The problem was that I had no good source for which 
window messages were sent upon creation. I only knew 
the obvious ones, like UM_CREATE and UMJCCREATE. 

Turbo Debugger for Windows came to the rescue. By 
setting the option to display window messages for an 


Lillie Big Lon 


Peer to Peer LAN, to 250 nodes 
, $75 total software cost! 

No matter how many nodes! 

Use Ethernet, Arcnet or 

serial/parallel/modem to connect. 


► Mixed mode routing 

Any combination of above connection is possible 
on any given node. 

. Use with windows 

Seen as 100% compatible 
Microsoft Network 
by Windows 3 jo 



Information Modes 

P.O. Drawer F 
Denton TX 76202 
817-387-3339 Techline 
817-382-7407 Fax 

1-800-628-7992 Orders 



The $25 Network 


IV v the 1st truly low cost LAN 

• Connect 2 or 3 PCs, XTs, ATs, PS/2S 

• Uses serial ports and 5 wire cable 

• Runs at 115K baud, up to 90 feet 

• Transfer 8500 bytes per second (ATs) 

:• Runs in background, totalty transparent 

• Share any device, any file, any time 

• Needs only 15K of ram 

• Just $25 per network, NOT PER NODE! 

• Replace all file transfer software 

• Version 2.3P now has TinyMAIL 

« OVER 20.000 SOLD WORLDWIDE 

Skeptical? We make believers! 


□ Request 246 on Reader Service Card □ 


Want to get the source code for 
the Borland 3D Chart Control? 


ToolsKan 


./■ i o • VBX 

Visual Basic Toolkit 


$99 


For SDK & Visual Basic 
3D Chart 

- Over 30 of 2D & 3D chart styles 

- Rotation & scrolling 

- Supports printing & clipboard 

Toolbox 

- Creates buttons from bitmaps 
or text 

- Supports scrolling 

- 3D buttons w/ color customization 

- Single/multiple/no-state button 
groups 

Ribbon 

- 3D items with color customization 

- Supports combobox, text, & buttons 

Field Validation 

- Validates date, time, number fields 
& "PIC" statements 


Meter 

- Creates vertical, horizontal, & 
circular gauges with choice of 
needle or color bar as indicators 

- Linear & logarithmic scales 

Table 

- Column & row split windows 

- Multiple row & column selections 

- Check boxes/radio buttons/bitmaps/ 
editable/combobox column 

- Input validation 

- Color customization 

Status Bar 

- Auto scrolled text 

- Stretchable field width 

- Colored progress bar 

- Show date, time, & key states 



Windows SDK Bundle $199 

$199 SDK DLL Bundle includes Table, Toolbox, 
Status Bar, Ribbon, Field Validation & Meter. 


Split windows 



Consulting & 

Contract Programming Available 


Free Demo from BBS. 

No Royalties. 30-day MBG. 
Optional with source code. 


Tel: (408) 263-9881 
Fax: (408) 263-9883 
BBS: (408) 263-0892 


Kansmen Corporation 
P.O. Box 360070 
Milpitas, California 95036 
USA 


□ Request 247 on Reader Service Card □ 


March 1994 


Windows/DOS Developer’s Journal — Page 79 















































OWL object, l was able to catch all the messages (some¬ 
thing which SPY can't do, since it only works on a window 
that has already been created). It turns out that WM_SH0U- 
UINDOU is sent immediately after the call to ShowUindowO. 
Calling RenewPlacementO in response, eliminates the flicker. 
Just don't forget to only call RenewPlacementO on the first 
message, because another call will generate another 
UM_SH0UUIND0U. rsize.cpp (listing 6) and rsize.mak (listing 7) 
contain the final result. Note that both the C and 
C++/OWL implementations share identical copies of 
plac.c, placment.h, and rsize.def. 

I'm still hoping to find a good reference for the order 
of events upon creation and destruction. I got a pretty 
good idea from working on this program, and I just might 
do the research myself. If anyone knows of a good source 
of this information, please share it with the rest of us. Be¬ 
tween the Waite Group's API Bible and Undocumented Win¬ 
dows (Schulman, Maxey, and Pietrek, Addison-Wesley, 
1992), I already have all the individual messages docu¬ 
mented, I'm just looking for the order in which they are 
sent. 

Your favorite application framework, or other language 
for that matter, should support one of the above methods. 
It's these little touches that make your windows program 
feel more professional. □ 
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Listing 7 rsize.mak 


# RENEWSIZ.MAK make file 

# . 


WINLINK=tlink /c In /Tw 
/Le:\bc\classlib\lib;e:\bc\owl\lib;e:\bc\lib 
WINLIB=import mathws owlws cws tclasss 
WINCObcc -c -w-par -P -W -2 

rsize.exe : rsize.obj plac.obj 

$(WINLINK) c0ws plac rsize, rsize. NUL. $(WINLIB). rsize 

plac.obj: plac.c placment.h 
$(WINCC) -1$(INCLUDE) plac.c 

rsize.obj: rsize.cpp placment.h 
t(WINCC) -I$(INCLUDE) rsize.cpp 
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Seven Borland C++ v4.0 Tips 

Ron Burk 


PC Windows C++ compilers are complex packages - 80Mb seems to be the 
going rate if you install everything that they come with. I use three packages 
(Borland, Microsoft, and Symantec), and my experience shows that an upgrade 
to a new major version always introduces a few problems. This article looks at 
some of the hitches I ran into when i threw out Borland C++ vB.1, installed 
v4.0 and started compiling. Some of these are specific to my way of working; I 
typically use the command-line versions of the compilers so that I can use a 
single makefile and easily switch between vendors at a moment's notice. 

Get the Good License 

As I mentioned in the Readers' Forum section last month, Borland C++ v4.0 
shipped with possibly the most onerous license agreement terms that a PC 
compiler has ever come with - it required you to contact Borland for permis¬ 
sion if you distributed more than 10,000 executables that you made with the 
compiler, for example. As I expected, Borland responded to vociferous com¬ 
plaints and almost immediately created a revised license that contained none 
of the restrictions about the volume of distribution or avoiding competition 
with Borland development tools. 

The January 10 InfoWorld reported that Borland will include the new license 
with all new copies of the compiler. However, if you purchase one of the older 
copies already in the distribution channel, you can contact Borland via phone 
at (800) 331-0877 to obtain a revised license agreement. 


Ron Burk is the editor of Windows/DOS Developer's Journal and has been a program¬ 
mer for 12 years. He is working on a book tentatively titled WinHelp for Programmers 
and Technical Writers. You may contact him at Burk Labs, P.O. Box 3082, Redmond, WA 
98073-3082. CIS: 70302,2566. Internet: ronb@rdpub.com (“. . . luunetlrdpublronb”). 


March 1994 


Windows/DOS Developer’s Journal — Page 81 











Use brcexe, Not rcexe 

When I first started remaking some code with the new 
compiler, I quickly got the errors shown in Figure 1. The 
addresses that the error messages refer to reside in Bor¬ 
land's runtime code. Apparently Borland ships with Mi¬ 
crosoft's version of the resource compiler as well as their 
own, and Microsoft's rc.exe mistakenly believes that Bor¬ 
land's runtime code contains some DGROUP references 
that will cause problems in multi-instance programs. 

The reason I was using rc.exe in the first place was to 
make it easier to use a single makefile for all three com¬ 
pilers (Borland, Microsoft, and Symantec). When I switched 
to brc.exe (Borland's resource compiler), I didn't have to 
see the annoying error message anymore. In general, 
you're probably better off using brc.exe anyway, as it has 


Figure 1 Typical RC errors with Borland C++ v4.0 


Microsoft® Windows Resource Compiler Version 3.10 

Copyright© Microsoft Corp. 1985-1992. All rights reserved. 

RC : warning RW4005: Segment 3 (offset 0686) con¬ 
tains a relocation record pointing to the automatic 
data segment. This will cause the program to crash 
if the instruction being fixed up is executed in a 
multi-instance application. If this fixup is necessary, 
the program should be restricted to run only a sin¬ 
gle instance. 

RC : warning RW4005: Segment 3 (offset 06EB) con¬ 
tains a relocation record pointing to the automatic 
data segment. This will cause the program to crash 
if the instruction being fixed up is executed in a 
multi-instance application. If this fixup is necessary, 
the program should be restricted to run only a sin¬ 
gle instance. 



Figure 2 PIF settings to give TLINKplenty of 
memory 


fewer limitations and bugs than Microsoft's resource com¬ 
piler in my experience. 

Change Your .pif File 

Borland's readme.txt file points this out, but TLINK 
wants more extended memory than in the past, so your 
default PIF file for your DOS shells is probably going to 
result in out-of-memory errors. As Figure 2 shows, I just 
set the memory limit fields in the PIF editor to -1, so that 
my DOS shell's access to extended memory has no artifi¬ 
cial limit. 

Exception Handling Takes Space 

Borland C++ v4.0 is the first of the three compilers I 
use to implement exception handling. That has some im¬ 
plications you might not have considered, though. The 
evolving ANSI standard calls for the standard new operator 
to throw an exception if it runs out of memory, and that 
means that if you are compiling a C++ program, the run¬ 
time code for exception handling will be linked in whether 
your program explicitly makes use of it or not. Borland 
also makes exceptions available to C programs, so it turns 
out that they pay this extra space penalty as well. 

This is most likely to surprise someone who is using 
the compiler to compile and link a small DOS utility. For 
example, with my usual compiler options, a 'Hello World' 
program that compiled into about a 9Kb .exe under Bor¬ 
land C++ v3.1 compiles into nearly 30Kb under Borland 
C++ v4.0. The command-line compiler has an option f-x-') 
to disable exception handling, but that merely affects the 
language the compiler accepts and is not smart enough to 
keep that 20Kb of runtime exception handling code from 
getting linked in. 

Gary Blaine, one of the people who help provide Bor¬ 
land support on CompuServe's BCPPWIN forum, posted a 
suggestion that seems to work well. Fie suggested includ¬ 
ing a stub function like this: 

void _ExceptInit(void) {} 

to keep the linker from linking in exception handling code 
if you are not using it. 

_ExceptInit() is a C function, so if you are compiling a 
C++ program instead, make sure you use this stub defini¬ 
tion rather than the previous one: 

extern "C" { 

void _ExceptInit(void) {} 

}; 

to avoid linking in the 20Kb of exception code. Also, 
make sure your C++ code does not throw any exceptions. 
To prevent new from throwing an exception when it is out 
of memory, call set_new_handler(0). 

Upgrade Your Bounds-Checker/W 

One of the problems about Borland C++ v3.1 was that 
some of its internal debugging tables were limited to 
64Kb, so a good-sized C++ program could overflow them 
fairly easily. Borland has revised some internal file formats 
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This application has vio 
of an invalid instruction 
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Quit all applications, qu 
computer. 

lated system integrity due to execution 
and will be terminated. 

t Windows, and then restart your 

OK j 


this, as the result will most likely be an hourglass cursor 
and a hung application. 

As I am writing this, Nu-Mega (makers of Bounds- 
Checker) is working on an update that will be compatible 
with Borland C++ v4.0 executables. By the time you read 
this, there is a good chance that the update will be avail¬ 
able; you can contact Nu-Mega directly to find out. 


Figure 3 DOS box crash from hitting Ctri-C during 
make 


so that that is not a problem. Unfortunately, one side ef¬ 
fect of this change is that one of the tools I use most 
often, Bounds-Checker for Windows v2.0, will not work on 
Borland C++ v4.0 executables. Don't even bother trying 


Get Patches for Chicago 

Borland C++ v4.0 can generate 32-bit executables that 
work with Win32s and Windows NT, but they don't work 
with the current prerelease (M5) of Chicago. Nor can you 
run Borland's tools (at least, not the 32-bit ones) under 
Chicago. For $10, you can now obtain an upgrade CD- 
ROM that lets Borland C++ 4.0 work with Chicago. Con¬ 
tact Borland at (800) 645-4559 to order. 
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GCP++?GENISYS.com 


MICROSOFT 

windows, 

COMIWIBLE 
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Sound & Vision Edition 


A hypertext / hypermedia Help Database Development Kit 
with two royalty free help engines and a help compiler with a 
built in cross reference tool. The current version is 10.0. 


ONE source generates help for MANY target formats like; 
Windows, OS/2, Microsoft Multimedia Viewer, THELP, 
DESQview/X, QuickHelp, PopHelp, word processors, text 
documents with table of contents, glossary and index. 

Write Once Help Many ! 


Supports Topics, PopUps, Links, Keywords, text formats, 
navigational and structural facilities, target code insertion, 
multiple module files, automatic Pascal/C/C++ reference 
generation, exception handling, graphics, sound, groups, 
multiple file target databases, Application Launch, user 
defined link templates, auto exports creation, and more. 

Get a demo version of HLPDK from CompuServe, Internet, 
PsL and other popular catalogs and BBS's. 

Order your copy from ISofl D&M or PsL today ! 


$50 


+S&H 


HyperAct, Inc. 

P.O.Box 5517, Coralvilie, IA 52241 
Tel/Fax (319) 351-8413 
CompuServe 76350,333 
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Macro 
Language 
"To Go" 


Easily add Netlogic’s full featured 
macro language facility to your 
Windows application — at a fraction of 
the time and cost of developing it your¬ 
self. Seamless integration. Full basic 
syntax. Integrated editor and debug¬ 
ger. Extendable and modifiable. For 
more information: Netlogic Inc., 915 
Broadway, New York, NY 10010. 
Phone 800-638-0048. Fax 212-533-9524 

Pro Macro ™ 

Your Application’s Shortcut to Power 
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Cpert 


Serial Communications for C/C+ + 

✓ Ideal for DOS and embedded applications 

✓ Supports COM1 to COM4 and custom configurations 

✓ Simultaneous serial communications 

✓ Baud rates from 50 to 115200 

✓ Built-in hardware and software handshaking 

✓ Interrupt driven transmitter and receiver 

✓ Optional direct transmit mode 

✓ Adjustable transmit and receive queues 

✓ Queues as large as 65534 bytes 

✓ Supports NS16550 UARTs 

✓ Developed in assembly for optimum speed and size 

✓ Xmodem and Zmodem file transfer 

✓ Source included 

✓ No royalties 

$75 ( plus shipping ) 


d3ri Productions 
39120 Argonaut Way, Ste 772 
Fremont, CA 94538 
it 510-794-0616 v 
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USING C++ OBJECTS WITH 
SQL RDBMS’s??? 

The Solution Isn’t Obvious, It's 

SUBTLEWARE™ FOR C++/SQL 


* Uses your C++ Class 
Definitions 

* Fully supports the C++ 
Object Model 

* Automatically generates 
SQL mapping code 

* Provides Portable Object 
Persistence across a variety 
of SQL RDBMS’s 


* Works with your existing 
RDBMS’s and tools 

* Shortens your development 
and maintenance time 

* Fits into most C++ 
environments, including 
Borland C++ and Visual 
C++ 


ANSI SQL Engine 
Introductory Price $299 


CALL 1-508-663-5584 

30 Day Money Back Guarantee 
Ask about availability of other 
Database Specific Modules y 


Subtle Software 
Inc. 

1 Albion Road 
Billerica, MA 01821 
FAX: 508-663-5685 


© 1994 Subtle Software, Inc Subdeware "■ is a trademark of Subtle Software, Inc 
Other product names are trademarks of their respective holders 
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Phone Sound: Simple! 

For Windows/DOS Voice Mail & Fax Developers 


Professional 
Tools for 
your Voice 
Mail, Fax & 
Audiotex 
Applications 


Multimedia Wave (16, 8 & 
MS ADPCM), linear 16 & 
unsigned 8, plus Dialogic 4 
& 8 at any sample rate! 

4. Scribe Transcription 
Utility for DOS plays digital 
audio files in the background 
without voice mail hardware! 

5. Add Text-to-Speech 
capability to your apps with 
VoxFonts ™, our "software 
only" text-to-speech library! 



1. Create fantastic prompts 
and save time with 
VFEdit®\ Record, crop, cut, 
copy, paste, mix, fade, echo, 
volume & more with your 
Dialogic™ D4x/12x boards 

2. Add Voice Mail power to 
your MS Windows apps with 
TI/F DLL ™, our Tel I/F 
Dynamic Link Library 

3. Audio ToolBox™ 
converts to and from 


Order Now: 1-800-234-VISI 


Voice Information Systems: 24 N Merion Ave, Bryn Mawr, Pa 19010 
^Tel^l5-7^^035/BBS^215-747-5062^a\jJ^00-234-F7(IT^J 
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IMWHelp 


Window/ Help Authoring Tool 


Professional quality help files 
in 1/4 the time!! 

• Edit text directly in IMWHelp 

• Build hypertext links to: topics, 
definitions, subjects 

• Glossary automatically created 

• Bitmaps incorporated 

• Desktop publishing features 

• Print topics, help file, customized 
reports 

• Spell check, replace verify/all 

• Easily reorganize topics, subjects, 
keywords 

• Uses Microsoft Help Compiler 

Single User: $89.95 

MC & Visa accepted, Shipping additional 

Call: IMCSI (212)319-1903 

425 Madison Ave., New York, NY 10017 
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I Does your company 
provide tools, products, 
or services for advanced 
Windows programmers? 
Then reach over 21,000 
serious programmers in: 

Windows/POS 

□ developers journal 

Call 913-841-1631 today for 
information about 
advertising opportunities in 

Windows/DOS Developer’s Journal. 

Advanced. Serious. 

Technical. 


1 Brian 

Osborn - Continental Europe. 

1 +49 431-396895 


1 Ed - East 

1 Christine - Midwest 

Edwin - West 

1913-841-1622 

1913-841-6733 

1913-841-1626 


C and C++ DOCUMENTATION 


! AUTOMATED DOCUMENTATION ! 

• C-CALL ($69) Graphic-tree of caller/called 
functions, cross-ref, file/function index. 

■ C-CMT ($69) Creates/inserts/updates 
comment-blocks for each function, listing 
the functions and identifiers used by it. 

• C-METRIC ($59) Counts path complexity, 
counts comments, code, 'C' statements. 

1 C-LIST ($69) Lists and action-diagrams, 
or reformats into standard formats. 

• C-REF ($59) Creates cross-reference of 
local/global/define/parameter identifiers. 

■ $PEQIAL: C-DOC ($199) All 5programs 
integrated as DOS program (<15,000 lines) 
NEW! C-DOC Professional ($299) 

DOS, OS/2, Windows. 3-ring binder/case. 
Processes 150,000 lines, deterred reports. 
30-DAY Money-back guarantee CALL NOW 


SOFTWARE BLACKSMITHS INC. 

6064 St Ives Way, Mississauga 
ONT, Canada Voice/Fax (4161-858-446( 
L5N-4M1 Demos/BBS ?'416i-858-19ll 


see AD INDEX for our larger ad 
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JOBS 

PM 
Mac 
Oracle 
Progress 
Windows NT 
Smalltalk 
Case 
OS/2 

Our midwest Clients are using 
Leading edge technology you thought 
you’d only see on the coasts. Discover the 
heartland, our quality of life and our 
commitment to technology. 

Employer Paid fees only. 

All recruiters are certified by the NAPC. 

Brad Moore, C.P.C. 

600 N, Derby Lane. Suite 200. N. Sioux City, SD 57049 
(605)232-3205 Fax (605) 232-3159 
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SLSOOPE ™ 

The PC 5eria\ Analyzer 

5I_5C0PE a comprehensive aerial 
monitor / debugger enables users to 
examine activity on anyserial lineat 
baud rates up to 115k. Capture data 
to RAManddisk while viewing activity 
in selectable data formats including 
ASCII and EBCDIC Pattern searching, 
microsecond timestamp accuracy, 
keyboard interaction, macro s, and 
more! 



Manual and cable included. 

30 day money back guarantee 



63 Rock Cut Rd. Newburgh N.Y. 12550 
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Avoid Reboots: Use maker. Not make 

Bugs that require you to reboot your system can be 
extremely irritating, even if you only run into them once a 
week. On page 53 of the October Windows/DOS Devel¬ 
oper's Journal, I described my nomination for the nastiest 
PC C++ compiler bug, a bug in the Borland C++ v3.1 com¬ 
mand-line tools. If you compiled and ran your application, 
but then made a change and relinked without remember¬ 
ing to terminate the application, then TLINK would try to 
write to the .exe (still in use) and give you an 'Abort, Re¬ 
try, Fail?' message. Even worse, the only correct answer to 
the question was "Fail", since typing "A' would send your 
DOS box into a debugging mode and leave make.exe busy, 
requiring a complete system reboot to remedy the prob¬ 
lem! 


I'm sorry to say that not only is that bug still in Borland 
C++ v4.0, but they've added an easier way to crash your 
DOS box. During the first day of using Borland C++ v4.0 
to rebuild projects, I happened to hit Ctrl-C while TLINK 
was running and the result was the error shown in Figure 
3. This is an erratic problem; only about every fifth time 
does banking on the Ctrl-C key result in a crashed DOS 
box. At first, I thought this was a TLINK problem, but then 
I happened to get a similar crash when interrupting the 
resource compiler during a make. Richard Smith at Phar 
Lap suggested i try using maker.exe (a 16-bit utility) instead 
of make.exe (a 32-bit extended utility) and that indeed fixed 
the problem. So, if you use make, either stay away from 
the Ctrl-C key until it is completely done, or else use 
maker, exe instead. □ 



Developer's 

Marketplace 



We Understand The 
Programmer's Mind 


When the country's top firms look for the 
best developers available, they turn to 
Bateman. Why? Because we specialize in 
Microsoft Windows, NT, OS/2 and Macin¬ 
tosh recruiting nationwide. So if it's time for 
a career move, give us a call. We under¬ 
stand your skills, and the marketplace for 
them... we understand you. 

□Bateman Inc. 

5847A Uplander Way 
Culver City, CA 90230 
Tel: 310-641-4100 Fax: 310-641-2900 
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Multiple COM: Ports With Windows! 

* WINDOWS 3.x AND NT COMPATIBLE 

* 1.2.4 OR & PORT RS-232 BOARDS 

* WINDOWS UTILITY SOFTWARE 
PROVIDED 

* XT AND AT INTERRUPT JUMPERS 

* DRIVER AVAILABLE FOR 9 COM: PORTS 
WITH WINDOWS 3.1 

* MADE IN USA 

* EXCELLENT TECHNICAL SUPPORT 

SEALEVEL 5YSTEM5, INC. 
PO BOX 530 
LIBERTY, 5C 29657 

503-543-4343 
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A M5MLEVEL 

COMMUNICATIONS & I/O 


The Time 
Has Came... 

...to send for the latest copy of 
the free Consumer Information 
Catalog. It lists more than 200 
free or low-cost government 
publications. Send your name 
and address to: 

Consumer Information Center 
Department TH 
Pueblo, Colorado 81009 

U.S. General Services Administration 
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Diskette I/O 

Code Libraries 
Device Drivers 

VxDS 

Special Hardware 


Software for Conversion, 
Duplication, Analysis, 
and Data Recovery 


WE SPECIALIZE IN "ALIEN" 
NON-PC FORMATS. 

Write or call for a product brochure! 

WvTft PY po Box 5700 

y VJ-VlA. Eugene, OR 97405 

(800) 43-SYDEX or (503) 683-6033 
FAX (503) 683-1622 


Tools for Novell's Btrieve® 


Bsupport III Bsupportll 

Bed it 3.0 - Btrieve File viewer/editor. 
Banalyze 2.0 - Btrieve app. debugger. 

Brun 2.2 - BUTIL replacement plus source. 
Bcreate 2.0 • file creation utility. 

Bcheck 2.0 - Btrieve file analyzer. 

Xsupport 1.0 - build data dictionary 
(.DDF) for Access, OV, 
Crystal Rpts. 

Xport 2.0 - export/import CDF, SDF, 
dBASE. 

Call for information on additional 
products and FREE demo! 

Information Architects, Inc. p| ): (goo) 359-2721 
3130 Pine Tree Road (517)887-8000 

Lansing, MI 48911 Fax:(517) 887-2366 
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SpyWorks-VB 

For Visual Basic™ - Windows 

SpyWorks-VB allows you to do virtually 
anything in Visual Basic that is possible 
using other languages such as C. It 
includes controls that easily subclass 
VB forms and controls, detect keyboard 
events, and support callback functions. 
SpyWorks includes debugging tools to 
view message and event history, detect 
API parameter errors, Browse Windows 
memory and resources, and retrieve 
information about any window, form or 
control in the system. 

SpyWorks-VB is only $129 + $5 s&h ($15 
outside U S & Canada). Visa/MC orders 
include phone and exp. date. CA residents 
add 8.25% sales tax. Dual media - Requires 
VB2.0 

Desaw are 

5 Town & Country Village #790 

San Jose, CA 95128 

(408) 377-4770 fax:(408) 371-3530 
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Career Marke ting Associates 

7100 East Belleview Avenue, Suite 102 
Englewood. CO 80111 

Today, 1993 

Dear WINDOWS DEVELOPER: 

Do you know where the best 
Windows development jobs are? I spend 
my time looking for strong 
opportunities for Windows developers 
and software engineers. I might be 
looking for someone with your 
qualifications right now. And there you 
sit in the corner reading a magazine! 
Pay attention, this is your future we 
are talking about. Currently I have 
multiple jobs requiring Windows 
experience, C++, or GUI. If you are 
thinking about a career change, 
shouldn’t you be working with a 
specialist? All fees are paid by the 
company. Write, call, fax, or 
communicate by smoke signals, I’m, 
waiting to hear from you. / 


Sincerely, 



Gary Patton 
303-779-8890 
FAX 303-779-8139 



Windows 
Developer Jobs 


Specialists in jobs for software 
engineers in leading edge technology. 
Windows, PM, GUI, Languages, AI, 

Mac, CASE, Video, Realtime. 

Nationwide contacts with both large 
and small companies including equity 
startups. Many of our clients develop 
and publish commercial software 
products. Managed by graduate 
engineers. Never a fee to an 
applicant. 

1-800-231-5920 
Scientific Placement, Inc. 

SP1-8, Box 19949, Houston, TX 77224 (713) 496-6100 
SP1-8, Box 71, San Ramon, CA 94583 (510) 733-6168 
SPI-8, Box 4270, Johnson City, TN 37602 (615) 854-9444 
Fax: 713-496-6802 please use Fine Setting on Fax 
Email: Ascii preferred: Internet LSH@Scientific.com; 
^ CompuServe: 71250,3001; Genie: D.SMALL6 _ J 
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IPX Toolkit 


This custom control allows a Visual 

Basic developer to write distributed, 
client/server applications. The control 
abstracts the networking layer of a 
workstation and 
allows applications 
to communicate on 
top of various 

transports including 
IPX and NetBIOS. 

A separate Windows dynamic-link library 
(DLL) is available for each transport and 
is demand-loaded based on a 

workstation's networking configuration. 
S295 Per Transport. 

Intelec Systems 

10201 W. Markham, Ste. 101 
Little Rock, Arkansas 72205 
Tel (501) 221-3600 • Fax (501) 221-7412 
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LIBRARY 


Opt-Tech Sort/Merge 


^ New-Version 5 

High performance Sort/Merge/Select 
utility. Run as a stand alone 
utility or CALL as a subroutine. 

Supports most languages and 
filetypes including Btrieve 
and dBase. Unlimited filesizes 
multiple keys and much more. 

MS-DOS, Windows $149 
OS/2, UNIX $249 

Call to order or for free info. 


Opt-Tech Data Processing 

P.O. Box 678 
Zephyr Cove, NV 89448 

. (702) 588-3737 > 
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CDROMs for Work and Play! 


Giga Games CDROM $39.95* 

Over 2700 Games for Microsoft Windows and 
MSDOS. 250 Megs of games plus 150 Megs of 
source. Lots of educational games. July 1993. 

CICA MS Windows CDROM $29.95* 

2518 files of MS Windows programs. Utilities, 
games, source code, programming tools, fonts, 
drivers, icons. April 1993. 

Simtel MSDOS CDROM $29.95* 

650 Megabytes, 9000+ files.Programming tools, 
utilities, editors, education, source 
code and more. May 1993. 

* Shareware programs 
require separate payment 
to authors if found useful. 

1-800-786-9907 orders@cdrom.com 
FAX 1-510-674-0821 
$5 S&H per order (USA Canada Mexico) 

$10 overseas 1 -510-674-0783 AMEX/VISA/MC/COD 
l *\ All our disks are 

unconditionally guaranteed. 

Walnut Creek CDROM 

4041 Pike Lane, Suite D-699 
Concord, CA 94520 
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2 ™ 

. 

The Art of Visual Basic Programming ™ 

This amazing new book by J. D. Evans, Jr. unlocks 
the secrets of Windows and Visual Basic 
application design and programming. It explains 
Windows design from a unique and easy to 
understand perspective. Smart Objects, Hybrid 
Objects, Control Coupling, Events, Focus, Event 
Triggering, Visibility, Form and Module Code 
Placement, DLL Parameter Passing, Variable 
Scope, Strings, and Structures are described and 
explained. Enlightening allegories and annecdotes 
make this one of the most unusual and informative 
Windows books ever written. This book is the 
Rosetta stone for Windows and Visual Basic! 


Book: $29.95 Companion Disk: $9.95 


ETN Corporation 

RD4 Box 659 Montoursville, PA 17754-9433 
(717) 435-2202 (Sales) (717) 435-2802 (FAX) 
AMEX/MC/VISA/Check/MO/PO/COD 
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1601 W. 23rd St., Suite 200 
Lawrence, KS 66046-2743 USA 
(913)841-1631 FAX: (913) 841-2624 


FREE 

PRODUCT 

INFORMATION! 


o receive additional information 
about the products advertised 
in this magazine, circle the 
corresponding Reader Service 
jmbers. Drop this postage-paid 
card in the mail, or FAX it to 
(913) 841-2624. 

Please circle no more than 
30 numbers. 
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FAST, PORTABLE C DEVELOPMENT TOOLS 



Lightweight Solutions lack features Heavyweight Solutions will cost 

and flexibility you may need a small fortune before 

to accomplish your mission. you even leave the ground. 


FairCom Offers A Full Line Of High-Performance Servers 
& Development Tools At Reasonable Prices. 


FairCom Servers® 

SQL & non-SQL 

These multi-threaded database servers 
offer a seldom-found solution for developers 
who demand control. While one may 
mandate SQL access, another's real-time 
demands may not tolerate the overhead 
associated with SQL. Our unique servers 
offer the full range of data accessibility: 
low-level speed; convenient ISAM-level; 
compatible SQL-level. Complete data 
integrity is achieved with multi-user 
transaction processing. Recovery of all 
committed transactions after a failure is fully 
automatic. The C developers 
'CLIENT/SERVER' solution: DOS nodes to 
UNIX servers; full commit and rollback; roll 
forward; precise control over your data 
and/or data base model; large files (4GB); 
complete client source code. On-line data 
backups with maximum data availability and 
protection. These servers are designed to 
achieve maximum power and flexibility 
without sacrificing control. 

r-tree® 

Report Generator 

r-tree report generator provides complex, 
multi-line reports by virtually handling 
every aspect of report generation. Your 
only programming requirement is to call 
the r-tree report function, which reads 
c-tree data files, performs calculations, 
monitors control breaks and 
accumulators and produces a formatted 
report. 


c-tree Plus® 

High Performance Data Management 

Based on the most advanced B+ Tree 
routines available today, c-tree Plus gives 
you unprecedented control over your file 
management needs. With unparalleled 
sophistication, c-tree Plus has established 
itself as the premier choice for commercial 
development. Use the low-level routines or 
take advantage of the high-level ISAM 
routines for high speed random or 
sequential access, c-tree Plus is distributed 
in complete C source code and is known 
for its portability and royalty-free licensing 
policy. Whether for single-user, multi-user or 
client-side application development, c-tree 
Plus delivers. Transaction processing is 
included in c-tree Plus as well as features 
like: fixed/variable length records and keys; 
dynamic space reclamation; high speed 
hashed data and index caching (and 
savepoints, abort, and rollback); full ISAM 
functionality; and batch operations. All 
functions are fully ANSI prototyped. Call for ^ 
a complete list of features. A 

Natural Query™ C 

Natural Language Tool 'T 

Produces ad hoc reports quickly and easily ’ 
from English sentences. It is the first 
low-cost, natural language tool designed for 
developers and a broad range of users. The 
QBE option has easy-to-use, pick and 
choose menus, making report specifications a 
snap. Available in VAR or end-user versions. 

□ Request 233 on Reader Service Card □ 


d-tree Toolbox® 

Application Development 

Productivity tools with: a complete 
portable screen handler; data 
dictionary; code generation; easy to 
use data base interface; menus; help 
text; data validation. d-tree‘s dynamics 
allow runtime control of program 
resources (screens, files, edits, etc.) 
not found in any other development 
package. Resources can be changed 
in memory, and/or swapped on/off of 
disk at runtime. Additional productive 
features include: flexible data 
windows; field masks; user-defined 
and field-level edits and data file 
reformatting. If you do application 
development on multiple platforms 
(DOS/UNIX), or you're debating 4GL 
versus C development, d-tree is for 
you. 



Call today for more information: 

( 800 ) 234-8180 

FAIRCOM® 

corporation 


4006 W. Broadway . Columbia, MO 65203 
(314) 445-6833 Fax (314) 445-9698 


FAIRCOM EUROPE 
Via Sottocorna 15/17 ■ ALBINO (BG) ITALY 
tel. 035/773464 • FAX 035/773806 


































AVOID EMBARRASSMENT! 



“A customer found a bug in 
our software with a tool 
called BOUNDS-CHECKER . . 

Why aren't vye using 

BOUNDS-CHECKER?” 



Use BOUNDS-CHECKER ™ V2.0 For Windows, The Automatic Bug Finder! 

Whether you' re the boss, the QA Manager or the programmer, it's your responsibility to ensure that 
your company's Windows programs are "bug-free" before they get into the hands of customers. 
If you're developing under C or C++, producing a "bug-free" Windows product is no longer a long 
and stressful experience. 


Announcing BOUNDS-CHECKER V2.0 For 

Windows, the software developer's "safety-net". 

Quickly and easily eliminate the hardest-to-find 
Windows errors that can take days - even weeks 
to find like: 

• API Parameter Errors 

• API Return Value Errors 

• Data and Heap Corruption 

• Resource Leakage Problems 

• Memory Leakage Problems 

• Processor Faults 

HOW IT WORKS - BOUNDS-CHECKER works by 
transparently setting hundreds of breakpoints within 
your program to monitor its behavior. When a bug 
is detected, BOUNDS-CHECKER immediately stops 
your program and pops up showing the problem. 

You can then inspect your program's source, vari¬ 
ables, stack and heap ... with BOUNDS-CHECKER's 
powerful display windows. 

EVENTLOGGING - BOUNDS-CHECKER nowlogs 
all Windows events. Many Windows bugs are diffi¬ 
cult to find because of the event driven, multi-tasking, mes¬ 
sage based nature of Windows. BOUNDS-CHECKER V2.0 For 
Windows introduces an event logging and display capability 
that captures all Windows messages, API calls, API returns 
and other events, The information is displayed in a high-level 
overview that lets you see how your program is interacting 
with Windows. When you want to see more detail, simply click 
to see a section expanded in great detail. 

EASY TO USE — Unlike other debugging tools, there's no 
learning curve with BOUNDS-CHECKER. Simply select your 
program's name from BOUNDS-CHECKER's menu; all the rest 
is automatic. There is nothing to link-in and no macros to 
compile into your program. All this plus the functionality of a 
heap checker, super spy utility, debug kernel, API debugger, 
and a post mortem tool into a single comprehensive auto¬ 
matic bug finder. 



BOUNDS-CHECKER Trapping a Parameter Validation Error 



For even greater debugging power get the 
Nu-Mega Power Pack! The Power Pack 
combines BOUNDS-CHECKER and Soft-ICE 
for Dos and Windows all bundled at great 
savings that put you in total control of both 
environments. And to make things even 
better you save over $400 and it comes in 
the great carrying case shown here. 

Call Today 


Call now for overnight delivery. 

BOUNDS-CHECKER V2.0 For Windows... Only $249 
BOUNDS-CHECKER For MS DOS... $199 
Order both versions & SAVE $150... Only $298 


BOUNDS CHECKER, SOFT-ICE. AND NU-MEGA TECHNOLOGIES are trademarks owned by Nu-Mega Technologies, Inc. All other trademarks are owned by their respective owners. 
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